@xmoon76/dsh-pi-tui 0.2.0 → 0.2.1

package/README.md

@@ -1,53 +1,413 @@
-# @xmoon76/dsh-pi-tui
+# dsh-pi-tui
+
+English | [简体中文](README.zh-CN.md)
+
+Release history: [CHANGELOG.md](CHANGELOG.md) · [简体中文更新日志](CHANGELOG.zh-CN.md)
 
 A third-party TUI mode for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`), built on a vendored fork of [pi-tui](https://github.com/MoonshotAI/kimi-code/tree/main/packages/pi-tui).
 
-This package is the `dsh.bundle` layer that makes `dsh --profile pi-tui` run a terminal UI instead of the browser GUI (`dsh --profile web`) or one-shot mode (`dsh --profile headless`). The vendored pi-tui fork (`@xmoon76/pi-tui`, with its local rendering fixes — the divergence ledger lives in the repo at `packages/pi-tui/AGENTS.md`) is bundled inside this package's build output — you only ever install this one package.
+Run `dsh --profile pi-tui` for a terminal UI instead of the browser GUI (`dsh --profile web`) or one-shot mode (`dsh --profile headless`).
+
+> **Status: working.** The TUI covers the main session loop — input → session events,
+> approvals, commands, session switching and full-text search — plus presets, skills,
+> model/settings menus, and slash commands. Rendering and input routing are verified
+> by headless tests (`@xterm/headless`) with no TTY or model connection needed.
+
+## Screenshot
+
+![dsh-pi-tui running in a terminal](https://raw.githubusercontent.com/XMoon/dsh-pi-tui/main/docs/dsh-pi-tui.png)
+
+## Layout
+
+The full repository layout lives in [AGENTS.md](AGENTS.md) (the contributor
+operating manual). In one line: the **repository root is the published
+`@xmoon76/dsh-pi-tui` bundle** (the only published package — its manifest
+declares `dsh.bundle.patch` and the `exports` point at the built `dist/`),
+and `packages/pi-tui/` is the vendored `@moonshot-ai/pi-tui` fork (rescoped
+to `@xmoon76/pi-tui`, private, never published — its divergence ledger lives
+in `packages/pi-tui/AGENTS.md`), bundled into the root package's build
+output.
+
+## Prerequisites
+
+- A DeepSeek Harness installation with profiles support (`dsh` on your `PATH`).
+- Node >= 22.19 (`^22.19.0 || >=24`, same range as dsh). Running from source
+  needs Node with native TypeScript support (>= 23.6) or the tsx ESM hook
+  (`node --import tsx/esm`, how dsh's own source launch works).
+- [pnpm](https://pnpm.io) only when installing from source.
 
 ## Install
 
-Prerequisite: a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) installation with profiles support.
+`dsh plugin` runs pnpm inside the target profile's directory, so the usual
+pnpm verbs (`add`, `remove`, `update`, `list`) all work.
+
+### Option A — from the npm registry (recommended)
+
+The published package is self-contained: the vendored pi-tui fork is bundled
+into its build output, so `@xmoon76/dsh-pi-tui` is the only package you install
+(`@xmoon76/pi-tui` stays private in this repo, like kimi-code keeps
+`@moonshot-ai/pi-tui` private):
 
 ```sh
+# install the bundle into the pi-tui profile (creates the profile if needed)
 dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui
+
+# run it
 dsh --profile pi-tui
 ```
 
-`dsh plugin` runs pnpm inside the profile; any dependency whose manifest declares `dsh.bundle` joins the profile's layer stack automatically.
+Any dependency whose manifest declares `dsh.bundle` joins the profile's layer
+stack automatically — no manual `cordis.patch.yml` wiring.
 
-## Verify / update / uninstall
+### Option B — from source
+
+Build artifacts are not committed (`dist/` for both packages is gitignored and
+the package `exports` point at the built files), so build before installing
+from a clone:
 
 ```sh
-dsh plugin --profile pi-tui -- list                              # is it installed?
-dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui       # registry installs
+git clone https://github.com/XMoon/dsh-pi-tui
+cd dsh-pi-tui
+pnpm install
+pnpm build        # pi-tui tsdown (packages/pi-tui/dist/) + root tsdown (dist/, bundles pi-tui)
+
+# file: — the bundle is copied into the profile at add time; rebuild + re-add
+# to refresh (see "Update / uninstall" below)
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@file:$PWD
+
+# link: — a live symlink instead; `pnpm build` output is picked up directly
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@link:$PWD
+```
+
+### Verify the install
+
+```sh
+dsh plugin --profile pi-tui -- list          # @xmoon76/dsh-pi-tui present
+dsh --profile pi-tui                         # TUI starts instead of the web GUI
+```
+
+### Update / uninstall
+
+```sh
+# registry installs:
+dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui
+# file: source installs copy at add time — rebuild + re-add to refresh
+# (link: installs track the repo live and need only `pnpm build`):
+pnpm build && dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@file:$PWD
+
 dsh plugin --profile pi-tui -- remove @xmoon76/dsh-pi-tui
 ```
 
-## Slash commands (selection)
+## Development
+
+```sh
+pnpm install
+pnpm build        # pi-tui tsdown (packages/pi-tui/dist/) + root tsdown (dist/, bundles pi-tui)
+pnpm test         # pi-tui's own suite (node --test) + dsh-pi-tui headless tests
+pnpm typecheck
+node --expose-gc scripts/bench.mts   # performance baseline (optional)
+```
 
-- `/sessions [query]` — session picker with search-as-you-type, grouping by workspace and live titles
-- `/search <query>` — full-text search over persisted session logs
-- `/title [title]` — show or set the current session's title
-- `/preset`, `/model`, `/settings`, `/export`, `/fork`, `/subagents` — see the command autocomplete (`/` + Tab)
+Tests drive the UI through `@xterm/headless` (see `test/virtual-terminal.ts`),
+so rendering and input routing are verified without a TTY or a model connection.
 
-## ⚠️ One surface per session
+### Development history (dogfooding)
 
-**Upstream limitation (a known dsh issue this TUI cannot fix):** dsh's session persistence has no cross-process coordination — each process numbers events from its own in-memory log length (`seq = log.length`) and appends to the same session file. When two processes hold the **same active session** at the same time (TUI + web GUI, two TUIs, TUI + any third-party plugin), one side's resume writes a `session/end-seed` marker and the other side's next append collides on the same seq — **the log corrupts and the session becomes unreadable** (`corrupt session log: seq gap in committed region`).
+This project started development on the browser surface (`dsh --profile web`) and
+switched to building itself with itself: since August 15 2026, all fixes and
+features are developed inside this TUI, the same way this README and the
+codebase are maintained. The dev loop runs on a dedicated `pi-tui-dev` profile
+installed with Option B's `link:` specifier
+(`dsh plugin --profile pi-tui-dev -- add @xmoon76/dsh-pi-tui@link:$PWD`)
+— a live symlink, so `pnpm build` is picked up without re-adding — while the
+`pi-tui` profile stays on the published registry package for real use.
 
-Therefore:
+## Extensions (early, stabilizing)
 
-- **Do not open the same active session in two surfaces at once** (TUI, web GUI, or any other plugin);
-- To switch surfaces, close the session in the current one first, then open it in the other;
-- This TUI ships a **divergence guard**: before each message send it checks whether another process has written the session file, and **blocks the send with a warning** when it has (pressing Enter again force-sends at your own risk — it may corrupt the log);
-- If a session is already corrupted, fix it with the [session repair script](#session-repair) below (close every process holding the session first).
+Since `0.2.0` the bundle ships a small, versioned extension surface so a
+third-party Cordis plugin can contribute chrome without touching the TUI
+internals. It is **early and stabilizing**: the capabilities below are the
+current set; the API version (`1`) is bumped only on breaking changes, and
+plugins must **feature-detect** capabilities instead of parsing the package
+version.
+
+All extension plugins remain standard DeepSeek Harness / Cordis plugins using
+`name`, `inject`, and `apply(ctx)` against the single `piTuiExtensions`
+service; the tiers are capability facades over that one service, not separate
+plugin systems or runtimes.
+
+The extension surface ships three tiers: a plugin imports ONLY the
+public entry — never the stable entry's internals (`TuiApp`,
+`TuiMainScreen`, `TuiAltScreen`) nor repository-relative paths.
+
+| Tier | Entry | Contract |
+|---|---|---|
+| Stable | `@xmoon76/dsh-pi-tui/extensions` | compatibility-oriented; additive-first; existing semantics never silently change; removal requires a planned breaking change |
+| Advanced | `@xmoon76/dsh-pi-tui/extensions/advanced` | experimental; minor releases may break; a migration note is required; no long-term shims |
+| Unstable | `@xmoon76/dsh-pi-tui/extensions/unstable` | NO compatibility guarantee; implementation may change anytime |
+
+All tiers reuse the SAME shared extension runtime: caller-fiber ownership,
+surface lifecycle, invalidation, capability discovery. Do not fork a second
+ownership/lifecycle model per tier. The tiers have grown since Phase 1:
+
+- **Advanced** (`ADVANCED_API_LEVEL = 1`, Phase 2 + Phase 4): normalized
+  input capture, focused interactive surfaces (interactive managed
+  overlays), advanced editor control, the imperative UI broker
+  (select/confirm/input/notify), custom interactive UI and the host-state
+  facade (theme/title/working/tools-expanded) — still Host-mediated,
+  never raw terminal bytes. Author guide: `docs/extension-advanced.md`;
+  Pi capability reference: `docs/extension-capability-matrix.md`.
+- **Unstable** (`UNSTABLE_API_LEVEL = 1`, Phase 3): raw input
+  interception (observe/consume/rewrite, exclusive raw ownership), the
+  Host emergency fail-safe (triple-Esc), and a selected low-level surface
+  seam — NO compatibility guarantee; a broken plugin can disrupt Host
+  behavior. Author guide: `docs/extension-unstable.md`.
+- **Real-plugin validation (Phase 5):** the tier selection is proven by
+  real consumers in `examples/plugins/` — a
+  production-class vim modal editor (Advanced editor SDK), a
+  questionnaire form (Advanced imperative UI broker) and an interactive
+  shell (Unstable raw seam). The "which tier should I use?" decision
+  tree: `docs/plugin-authoring.md`.
+
+A plugin imports only the public entry:
+
+```ts
+import { PI_TUI_EXTENSIONS_SERVICE, type PiTuiExtensionService } from '@xmoon76/dsh-pi-tui/extensions'
+
+export const name = 'my-plugin'
+export const inject = ['tuiStartup', PI_TUI_EXTENSIONS_SERVICE]
+
+export function apply(ctx: Context): void {
+  const service = ctx.get(PI_TUI_EXTENSIONS_SERVICE) as PiTuiExtensionService
+  if (!service.api().capabilities.has('slot.chrome.header.badge')) return
+  service.register<{ text: string; tone?: 'info' | 'warning' | 'error' | 'success' }>(
+    'chrome.header.badge',
+    { id: 'my-badge', order: 100, description: 'A header badge from my plugin.' },
+    { text: 'my-badge', tone: 'info' },
+  )
+}
+```
+
+Current extension points (v1):
+
+| Slot | Semantics | Contribution |
+|---|---|---|
+| `chrome.header.badge` | list | a short `[badge]` after the host title |
+| `input.dock.item` | list | a dock line above the todo panel |
+| `chrome.footer.status` | list | a footer segment (host owns width/truncation) |
+| `input.widget.above` / `input.widget.below` | list | a bounded widget around the editor (M4 component kit) |
+
+Contributions are **plain data**, not render functions: a plugin supplies
+`HeaderBadge` / `DockItem` / `FooterSegment` / `InputWidget` values (text +
+semantic tone spans, or a structured `ExtensionView` tree for widgets) and
+the host owns rendering, ANSI compilation, width budgets and truncation.
+There is deliberately no `render(context)` callback in v1 — plugins never
+hold a rendering context, so a contribution can never capture or mutate
+host internals.
+
+Since `0.2.0` the widget slots (`input.widget.above` / `input.widget.below`)
+accept a bounded component kit: `ExtensionView` is a structured view tree
+(`text` / `markdown` / `spacer` / `stack` / `frame` / `rows` views with
+semantic style tokens) that the host compiles into private components. A
+plugin can add helper rows above or below the editor — for example a status
+widget or a quick-reference line — without touching the root layout, the
+editor, or focus. The host owns the row budgets: under height pressure the
+lowest-importance widgets collapse first, and the editor always survives.
+
+```ts
+service.register<InputWidget>('input.widget.below', {
+  id: 'my-widget',
+  order: 100,
+}, {
+  view: {
+    kind: 'text',
+    spans: [{ text: 'my-plugin ready', tone: 'success' }],
+  },
+})
+```
+
+Since M5 the extension surface also covers registries (plan §10):
+
+- `registerCommand(contribution)` — slash-command OWNERSHIP metadata
+  (`execution: 'local' | 'submission'`): a plugin-declared local command
+  always executes directly (never steered by the busy-Enter preference);
+  a submission command flows through the session policy. Actual execution
+  stays in the host's commands service; `/name args...` keeps
+  `rawInput` verbatim. Name conflicts are reported, never guessed.
+- `registerTheme(contribution)` — a named semantic palette selectable
+  from the /settings theme picker; the owner's unload falls back to the
+  built-in palette (a selected plugin theme never dangles).
+- `registerSetting(contribution)` — a settings row appended to the
+  /settings panel (label + current value + choices + optional rejection);
+  the host owns the panel.
+- `registerAutocomplete(contribution)` — an autocomplete provider
+  consulted after the host's own provider returns null (deterministic
+  order, per-provider isolation, latest-only commit).
+- `registerKeybinding(contribution)` — normalized-key → semantic-action
+  binding, routed by the host's InputRouter (M6). A plugin declares a key
+  with the public `NormalizedKey` shape (key + ctrl/alt/shift/super) and
+  a semantic action from the host's list (`submit-draft`, `queue-draft`,
+  `steer-draft`, `cancel-activity`, `open-search`, `toggle-fullscreen`,
+  `cycle-permission`). The host normalizes ALL terminal input (Kitty
+  CSI-u, modifyOtherKeys, legacy sequences) — a plugin never sees raw
+  escape data. Reserved host lifecycle keys (Ctrl+C/D/S/F/O/T/G/J,
+  Ctrl+Enter, Enter, Esc) cannot be claimed; plain printable keys never
+  fire a binding (typing always wins); bindings are non-capturing and
+  fire LAST in the precedence ladder (after questions, approvals,
+  overlays and the editor). The action executes through the host's own
+  paths — submission/session safety is never bypassed.
+- `registerMessageRenderer(contribution)` — a TRANSCRIPT message renderer
+  (M7, chain slot): receives a semantic `MessagePresentationSnapshot`
+  (immutable; never the mutable message or the container) and returns an
+  `ExtensionView` or `undefined` (abdicate → the next renderer → the host
+  fallback). Kind-scoped renderers apply to one message kind.
+- `registerToolRenderer(contribution)` — a TOOL card renderer (M7, keyed
+  slot): presents the card for ONE tool name from a
+  `ToolPresentationSnapshot` (callId, toolName, status, arguments,
+  result, expanded); the winner (lowest priority) abdicates to the next
+  renderer, then the host fallback. A priority tie on the same tool name
+  is an explicit error.
+  Renderers never stall the transcript: a throwing renderer is isolated
+  and the chain continues, and the message cache embeds the renderer
+  identity + registry revision, so an HMR/unload rebuilds exactly the
+  affected components.
+- `showOverlay(view, options)` — a MANAGED overlay lease (M8): the plugin
+  supplies an `ExtensionView` + sizing hints; the host mounts it through
+  its overlay broker (modal stacking, focus, fullscreen migration). The
+  returned lease is generation-scoped (the surface's final dispose closes
+  every still-owned lease), close() is idempotent, and hide()/show()
+  toggle visibility without closing. A plugin can never mount a raw
+  component or steal focus — the host owns the terminal and the overlay
+  stack.
+The [extension API v1 author guide](docs/extension-api.md) records the
+import rules, the full surface table, the lifecycle/render contracts, the
+M11 deprecation policy and the stability contract.
+
+The M10 acceptance fixture (plan §15): the repo ships a vim-mode fixture
+(`test/fixtures/vim-plugin/`) that validates the editor-extension seam — the
+packed public SDK is consumable by a third-party Cordis plugin, its
+replacement editor receives SEMANTIC `EditorInputEvent`s (never raw terminal
+bytes), and editor `create()`/`dispose()` work — importing ONLY
+`@xmoon76/dsh-pi-tui/extensions`. It is NOT a production Vim and NOT a
+Stable-API completeness proof: modal-mode behavior (insert/normal) is not
+part of the Stable contract, and the other public surfaces (commands,
+themes, settings, autocomplete, keybindings, renderers, overlays, widgets)
+have their own dedicated tests. Its CI gate forbids `@xmoon76/pi-tui`,
+`src/tui-app` and repository-relative internal paths: if a STABLE plugin
+ever needs a private import, the SDK is missing a capability (there is no
+`unsafeGetTuiApp()` escape hatch).
+
+- `registerEditor(contribution)` — the EDITOR SDK (M9, plan §14):
+  single-winner by priority (a tie is an explicit error); the winner
+  occupies the editor seat through the host's ATOMIC handoff (create →
+  transfer draft/cursor → mount → focus → dispose old). A creation throw
+  keeps the current editor working; winner unload restores the next
+  winner / the host default editor WITH the draft preserved. The plugin
+  editor receives an `EditorHost` (surfaceId, generation, getSnapshot,
+  replaceText, dispatch of semantic actions submit/queue-submit/steer/
+  open-external-editor, subscribe, invalidate) — but the host still owns
+  busy-Enter, Ctrl+Enter, local-command classification, paste protection,
+  approval/question capture, session guard/lock, external editor and
+  exit: a plugin editor can never bypass those.
+
+Lifecycle is host-owned: registrations are disposed when the plugin's Cordis
+fiber unloads (HMR, disable), regular and fullscreen both refresh, and
+`handle.invalidate()/replace()` re-render through the active screen. The
+`@xmoon76/dsh-pi-tui/builtins` entry is the Loader-only first-party
+contributor (version badge, turn/step counters, todo-summary dock item) —
+not a stable third-party SDK. Raw terminal access, pre-host input
+interception and full input ownership are NOT part of the Stable tier (see
+the Advanced/Unstable roadmap).
+
+## Slash commands (selection)
+
+- `/sessions [query]` — open the session picker: search-as-you-type over
+  session ids, titles, and workspaces, rows grouped by workspace with live
+  `filtered/total` counts, and titles loaded in the background as they are
+  read. Enter switches to the selected session.
+- `/search <query>` — full-text search over persisted session logs, then
+  switch to a hit.
+- `/title [title]` / `/rename [title]` — with an argument, set the current
+  session's title (pins it against automatic generation; titles appear in
+  the `/sessions` picker); **without an argument, regenerate the title from
+  the conversation — this overwrites the current title, including one you
+  pinned earlier**.
+- `/yolo` — switch to `danger-full-access` (alias of `/permission danger-full-access`).
+- `/queue` — per-item queue management: edit, delete, steer one, or insert a
+  message into the agent's inbox (the queue pane above the editor shows
+  pending messages; `Ctrl+S` steers them all at once, `Alt+↑` pulls them all
+  back into the editor).
+- `/status` — show the current session's stats and identity (turn counts,
+  token usage, workspace, installed dsh version).
+- `/preset`, `/model`, `/settings`, `/export`, `/fork`, `/subagents` — see
+  `dsh --profile pi-tui`'s command autocomplete (`/` + Tab).
+
+## Keybindings (selection)
+
+- `Ctrl+F` — toggle transcript search (the `/search <query>` overlay; a
+  second press closes it).
+- `Shift+Tab` — cycle the permission preset (read-only → workspace-write →
+  danger-full-access); the footer's mode slot badges every preset
+  (`[workspace-write]` / `[read-only]` / `[custom]`, with `[yolo]` flagging
+  the no-approval mode).
+- `Ctrl+S` — steer: with queued messages, sends the whole queue (plus the
+  draft, if any) into the running turn at once; otherwise sends the draft
+  alone. An idle agent starts a fresh turn with everything.
+- `Alt+↑` — dequeue: pull every queued message back into the editor draft.
+- `Ctrl+T` — toggle the full todo list; the dock above the editor always shows
+  the todo summary and background tasks, and queued input renders between
+  them.
+- `@` — file/folder mentions in the editor: `@` + Tab completes files from the
+  whole workspace (fd-backed when `fd` is on PATH, with a built-in recursive
+  fallback otherwise). The literal `@path` is submitted and the model reads
+  the file itself. With background work running, an empty editor's `↓` or
+  `Ctrl+J` opens the task browser over both surfaces:
+  - **subagent rows** (live continuable children) — `Enter` opens the child's
+    transcript read-only (`Esc` returns); they never register jobs records, so
+    this browser is their only glanceable home.
+  - **job rows** (bash and one-shot subagent jobs) — `Enter` shows the status
+    viewer only: a bash job's output read cursor belongs to the model's
+    `job_output`, and a one-shot subagent job record carries no child session
+    id, so the transcript is reached via `/subagents` (`s` stops a job).
+  The footer badge shows `[N tasks running · M agents · ↓ view]` while any
+  background work is live.
+
+## Launch options
+
+The TUI's startup row adds `--preset <id>` — the agent preset a fresh
+session starts on (falls back to `$DSH_PI_TUI_PRESET`, then the saved
+settings default). It exists because `/preset` only applies to a blank (not
+yet created) session, so launch-time selection is the other half of choosing
+a preset. All other flags are the dsh runner's own (`--session <id>`, …).
+
+## Session lifecycle
+
+Opening the TUI with no `--session` creates **no session at all**: the first
+user message (text, slash command, `Ctrl+S` steer, or `!` shell) starts it
+lazily. `--session <id>` still resumes immediately, and a local `!!` command
+runs without needing a session.
+
+## Verified in the P0 spike
+
+- Vendored pi-tui: the fork's own suite passes under `node --test` (run it as
+  the sync gate after every re-vendor; the count is deliberately not copied here —
+  `packages/pi-tui/package.json` is the single source of version facts).
+- `TuiApp` renders, accepts editor input, and handles Ctrl+C on a headless xterm.
+- The whole import chain (pi-tui, tui-app, `@deepseek-ai/dsh-cmdline`, commander)
+  loads under the tsx ESM hook — the dsh source-launch contract.
+- Native modifier-key addons are optional: on Linux the loader returns `undefined`
+  without attempting a load, and the non-TTY stdin path is guarded.
 
 ## Diagnostic log
 
-The TUI writes its own diagnostics to stderr and a log file (`ctx.logger` is invisible in this process — no exporter):
+The TUI writes its own diagnostics to stderr and a log file (`ctx.logger` is
+invisible in this process — no exporter):
 
 - Default file: `$DSH_HOME/logs/pi-tui-<pid>.log` (default `~/.dsh/logs/`);
 - Line format: `[tui] <ISO time> <level> <message> k=v ...`;
-- Default level `info`: key lifecycle events only (boot/resume/switch/exit, divergence-guard warnings, errors); `debug` additionally logs every guard check before a send.
+- Default level `info`: key lifecycle events only (boot/resume/switch/exit,
+  divergence-guard warnings, errors); `debug` additionally logs every guard
+  check before a send.
 
 Configuration (environment variables):
 
@@ -63,37 +423,39 @@ DSH_PI_TUI_LOG_LEVEL=debug dsh --profile pi-tui
 tail -f ~/.dsh/logs/pi-tui-*.log
 ```
 
-## Session repair
-
-**Background:** when a session log is corrupted (duplicate or missing seqs) dsh can no longer read that session. This repository ships a standalone repair script, `scripts/repair-session.mjs`: it locates the session file, diagnoses the damage, and repairs it — renumbering seqs (duplicates), truncating at the first missing/unparsable event (which cannot be recreated), or re-framing the log when the frame layout is wrong (dsh requires the first zstd frame to be exactly the header line; a whole-log single frame is structurally valid zstd but rejected by every dsh reader). It **always backs up the original before writing** and verifies the result with the same scans the reader performs (frame layout + event contiguity).
-
-**Dependency:** resolves `@deepseek-ai/dsh-session` from the dsh installation (auto-detected through the `dsh` launcher on PATH, or `--dsh-dir <path>`).
-
-**Repair one session (dry run by default; `--yes` writes):**
-
-```sh
-# Close every process holding the session first (TUI / web / plugins)!
-node scripts/repair-session.mjs session-ab79200b-0e36-4a62-a7a6-3ac620c05f1d          # diagnose + repair plan (no write)
-node scripts/repair-session.mjs session-ab79200b-0e36-4a62-a7a6-3ac620c05f1d --yes    # apply the repair
-```
-
-The original file is backed up to `session.jsonl.zstd.bak-<timestamp>` before writing (a failed backup aborts the write); the report prints the backup path.
-
-**Read-only scan of all sessions, listing damaged ids:**
-
-```sh
-node scripts/repair-session.mjs --scan
-```
-
-Prints one `CORRUPT <id>: <reason>` per damaged session; `no damaged sessions found` when everything is healthy.
-
-**Other options:** `--dsh-home <path>` sets the sessions root (default `$DSH_HOME` or `~/.dsh`); `--help` shows usage.
-
-## Development
-
-Source and tests live in the [dsh-pi-tui repository](https://github.com/XMoon/dsh-pi-tui) (`packages/dsh-pi-tui/`); headless tests drive the UI through `@xterm/headless` with no TTY or model connection.
+## Safety & operational notes
+
+- **One surface per session.** dsh has no cross-process session coordination:
+  a session open in TWO dsh processes (TUI + web, or two TUIs) can corrupt its
+  log. The TUI refuses to open a session already held by another live dsh
+  process (an `owner.lock` file next to the log, with a pid/starttime probe
+  for stale locks left by crashes — so the second surface is stopped at
+  OPEN time, not after the damage). For writes, the TUI detects the other
+  writer and blocks the send; the SAME action pressed again (Enter for a
+  submit, Ctrl+S for a steer, unchanged draft) forces through — an edited
+  draft, a swapped key, a new file revision, or a session switch invalidates
+  the force. Never run two surfaces on one session (full contract:
+  `docs/concurrency.md`).
+- **Session repair.** `node_modules/@xmoon76/dsh-pi-tui/scripts/repair-session.mjs`
+  repairs corrupted logs (`--scan` lists damage read-only; `--yes` applies with
+  a mandatory backup). A torn (truncated) tail is truncated at the last
+  complete frame and reported with exact byte accounting; references to a
+  duplicated seq are never auto-resolved — the repair refuses and asks for
+  `--duplicate-reference=first|last|segment`. Repaired logs are re-verified
+  with the dsh reader's own layout checks before the backup is considered
+  redundant. (Full repair contract, incl. the frame-layout constraint:
+  `docs/repair-session.md`.)
+- **Exit.** `/exit` (alias `/quit`) flushes the session with a 10s hard
+  timeout: a hung provider cannot trap the TUI. If the flush fails or times
+  out, the terminal prints a warning (the tail may not be persisted) and the
+  process still exits.
+- **Performance.** `scripts/bench.mts` (non-default) measures ingest,
+  projection, cold/warm rebuilds, streaming frames, theme switches, and heap;
+  the saved baseline lives in `docs/perf-baseline.md`. Unchanged transcript
+  messages reuse their rendered components, so the warm per-frame rebuild
+  does not grow with history.
 
 ## License
 
-MIT. The bundled pi-tui fork retains its upstream MIT license and authorship
+MIT. `packages/pi-tui` retains its upstream MIT license and authorship
 (Copyright (c) 2025 Mario Zechner; Moonshot AI fork).

package/README.zh-CN.md

@@ -0,0 +1,411 @@
+# dsh-pi-tui
+
+[English](README.md) | **简体中文**
+
+发布历史:[CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md) · [English Changelog](CHANGELOG.md)
+
+为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`) 提供的第三方 TUI 模式,构建于 [pi-tui](https://github.com/MoonshotAI/kimi-code/tree/main/packages/pi-tui) 的内置(vendored)fork 之上。
+
+运行 `dsh --profile pi-tui` 即可获得终端界面,替代浏览器界面(`dsh --profile web`)或一次性模式(`dsh --profile headless`)。
+
+> **状态:可用。** 该 TUI 覆盖了主会话流程——输入 → 会话事件、审批、
+> 命令、会话切换与全文搜索——以及预设(presets)、技能(skills)、
+> 模型/设置菜单和斜杠命令。渲染与输入路由由无头测试
+> (`@xterm/headless`)验证,无需 TTY 或模型连接。
+
+## 截图
+
+![dsh-pi-tui 运行在终端中](https://raw.githubusercontent.com/XMoon/dsh-pi-tui/main/docs/dsh-pi-tui.png)
+
+## 目录结构
+
+完整的仓库布局见 [AGENTS.md](AGENTS.md)(贡献者操作手册)。一句话概括:
+**仓库根目录就是发布的 `@xmoon76/dsh-pi-tui` 包**(唯一发布的包——其
+清单声明 `dsh.bundle.patch`,`exports` 指向构建后的 `dist/`),而
+`packages/pi-tui/` 是 `@moonshot-ai/pi-tui` 的内置 fork(重命名为
+`@xmoon76/pi-tui`,私有,永不发布——其分叉修改清单见
+`packages/pi-tui/AGENTS.md`),构建时被打进根包产物。
+
+## 前置要求
+
+- 一个支持 profile 的 DeepSeek Harness 安装(`dsh` 已在 `PATH` 中)。
+- Node >= 22.19(`^22.19.0 || >=24`,与 dsh 相同范围)。从源码运行需要
+  原生支持 TypeScript 的 Node(>= 23.6)或 tsx ESM 钩子
+  (`node --import tsx/esm`,dsh 自身源码启动的方式)。
+- 仅从源码安装时需要 [pnpm](https://pnpm.io)。
+
+## 安装
+
+`dsh plugin` 会在目标 profile 目录内运行 pnpm,因此常用的 pnpm 动词
+(`add`、`remove`、`update`、`list`)都可用。
+
+### 方式 A — 从 npm registry 安装(推荐)
+
+发布的包是自包含的:内置的 pi-tui fork 被打进了构建产物,所以只需安装
+`@xmoon76/dsh-pi-tui` 一个包(`@xmoon76/pi-tui` 在本仓库保持私有,就像
+kimi-code 保持 `@moonshot-ai/pi-tui` 私有一样):
+
+```sh
+# 把包安装到 pi-tui profile(必要时会创建该 profile)
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui
+
+# 运行
+dsh --profile pi-tui
+```
+
+任何在清单中声明了 `dsh.bundle` 的依赖都会自动加入 profile 的层栈
+(layer stack)——无需手动配置 `cordis.patch.yml`。
+
+### 方式 B — 从源码安装
+
+构建产物不提交(`dist/` 对两个包都在 gitignore 中,且包的 `exports`
+指向构建后的文件),所以从克隆安装前需要先构建:
+
+```sh
+git clone https://github.com/XMoon/dsh-pi-tui
+cd dsh-pi-tui
+pnpm install
+pnpm build        # pi-tui tsdown (packages/pi-tui/dist/) + 根 tsdown (dist/, 打入 pi-tui)
+
+# file: — 添加时把包复制进 profile;重新构建后需重新 add 以刷新
+#(见下方"更新 / 卸载")
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@file:$PWD
+
+# link: — 使用实时符号链接;`pnpm build` 的产物会被直接读取
+dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@link:$PWD
+```
+
+### 验证安装
+
+```sh
+dsh plugin --profile pi-tui -- list          # 应包含 @xmoon76/dsh-pi-tui
+dsh --profile pi-tui                         # 启动的是 TUI 而不是 Web GUI
+```
+
+### 更新 / 卸载
+
+```sh
+# registry 安装:
+dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui
+# file: 源码安装在 add 时复制——重新构建并重新 add 以刷新
+#(link: 安装实时跟踪仓库,只需 `pnpm build`):
+pnpm build && dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@file:$PWD
+
+dsh plugin --profile pi-tui -- remove @xmoon76/dsh-pi-tui
+```
+
+## 开发
+
+```sh
+pnpm install
+pnpm build        # pi-tui tsdown (packages/pi-tui/dist/) + 根 tsdown (dist/, 打入 pi-tui)
+pnpm test         # pi-tui 自带套件 (node --test) + dsh-pi-tui 无头测试
+pnpm typecheck
+node --expose-gc scripts/bench.mts   # 性能基线(可选)
+```
+
+测试通过 `@xterm/headless` 驱动 UI(见
+`test/virtual-terminal.ts`),因此无需 TTY 或模型连接
+即可验证渲染与输入路由。
+
+### 开发历史(dogfooding)
+
+本项目最初在浏览器界面(`dsh --profile web`)上开发,后来转为用自己开发
+自己:自 2026 年 8 月 15 日起,所有修复与功能都在这个 TUI 内部完成,就像
+本 README 与代码库的维护一样。开发循环运行在专用的 `pi-tui-dev`
+profile 上,使用方式 B 的 `link:` 说明符安装
+(`dsh plugin --profile pi-tui-dev -- add @xmoon76/dsh-pi-tui@link:$PWD`)
+——实时符号链接,`pnpm build` 后无需重新 add 即可生效——而 `pi-tui`
+profile 保持安装已发布的 registry 包用于真实使用。
+
+## 扩展(早期,稳定化中)
+
+自 `0.2.0` 起,该 bundle 携带一个小的、带版本号的扩展面,让第三方
+Cordis 插件无需接触 TUI 内部即可贡献 chrome。它**处于早期、稳定化中**:
+下面的能力是当前集合;API 版本(`1`)只在破坏性变更时递增,插件必须
+**按能力特性检测**,而不是解析包版本。
+
+所有扩展插件仍是标准 DeepSeek Harness / Cordis 插件,使用 `name` /
+`inject` / `apply(ctx)`,统一依赖唯一的 `piTuiExtensions` 服务;三层
+只是该单一 Service 上的能力 facade,而非独立的插件系统或 runtime。
+
+扩展面分为三个层级:插件只导入**公开入口**——绝不导入 Stable 入口的
+内部(`TuiApp`、`TuiMainScreen`、`TuiAltScreen`)或仓库相对路径。
+
+| 层级 | 入口 | 契约 |
+|---|---|---|
+| Stable | `@xmoon76/dsh-pi-tui/extensions` | 面向兼容;只增不改;既有语义永不静默变更;删除需计划内破坏性变更 |
+| Advanced | `@xmoon76/dsh-pi-tui/extensions/advanced` | 实验性;minor 版本可破坏;需迁移说明;不做长期 shim |
+| Unstable | `@xmoon76/dsh-pi-tui/extensions/unstable` | 不保证兼容;实现可随时变更 |
+
+所有层级复用同一个共享 Extension Runtime:caller-fiber 所有权、surface
+生命周期、失效机制、能力发现。不要按层级复制第二套所有权/生命周期
+模型。第一阶段之后各层级已逐步落地:
+
+- **Advanced**(`ADVANCED_API_LEVEL = 1`,Phase 2 + Phase 4):规范化输入捕获、
+  聚焦交互表面(交互式托管 overlay)、高级编辑器控制、命令式 UI broker
+  (select/confirm/input/notify)、自定义交互 UI 与 host-state facade
+  (theme/title/working/tools-expanded)——仍由 Host 中介,绝不接触 raw
+  terminal 字节。作者指南:`docs/extension-advanced.md`;Pi 能力参考:
+  `docs/extension-capability-matrix.md`。
+- **Unstable**(`UNSTABLE_API_LEVEL = 1`,Phase 3):raw 输入拦截
+  (observe/consume/rewrite、exclusive raw 所有权)、Host 紧急 fail-safe
+  (三连 Esc)与精选低层 surface seam——不保证兼容;损坏的插件可能
+  破坏 Host 行为。作者指南:`docs/extension-unstable.md`。
+- **真实插件验证(Phase 5):**层级选择由真实消费者验证,见
+  `examples/plugins/`——生产级 vim 模态编辑器
+  (Advanced editor SDK)、questionnaire 表单(Advanced 命令式 UI
+  broker)与交互式 shell(Unstable raw seam)。"该用哪一层?"决策树:
+  `docs/plugin-authoring.md`。
+
+插件只导入公开入口:
+
+```ts
+import { PI_TUI_EXTENSIONS_SERVICE, type PiTuiExtensionService } from '@xmoon76/dsh-pi-tui/extensions'
+
+export const name = 'my-plugin'
+export const inject = ['tuiStartup', PI_TUI_EXTENSIONS_SERVICE]
+
+export function apply(ctx: Context): void {
+  const service = ctx.get(PI_TUI_EXTENSIONS_SERVICE) as PiTuiExtensionService
+  if (!service.api().capabilities.has('slot.chrome.header.badge')) return
+  service.register<{ text: string; tone?: 'info' | 'warning' | 'error' | 'success' }>(
+    'chrome.header.badge',
+    { id: 'my-badge', order: 100, description: 'A header badge from my plugin.' },
+    { text: 'my-badge', tone: 'info' },
+  )
+}
+```
+
+当前扩展点(v1):
+
+| Slot | 语义 | 贡献 |
+|---|---|---|
+| `chrome.header.badge` | list | host 标题后的短 `[badge]` |
+| `input.dock.item` | list | todo 面板上方的一行 dock |
+| `chrome.footer.status` | list | 一个 footer 段(host 拥有宽度/截断) |
+| `input.widget.above` / `input.widget.below` | list | 编辑器周围的有界 widget(M4 组件套件) |
+
+贡献是**纯数据**,不是 render 函数:插件提供 `HeaderBadge` / `DockItem` /
+`FooterSegment` / `InputWidget` 值(文本 + 语义 tone spans,或 widget 的
+结构化 `ExtensionView` 树),渲染、ANSI 编译、宽度预算与截断全部由 host
+负责。v1 刻意没有 `render(context)` 回调——插件从不持有渲染上下文,
+贡献永远无法捕获或修改 host 内部。
+
+自 `0.2.0` 起,`input.widget.above` / `input.widget.below` 两个 widget slot
+接受有界组件套件:`ExtensionView` 是结构化视图树(`text` / `markdown` /
+`spacer` / `stack` / `frame` / `rows` 视图 + 语义样式 token),由 host 编译
+成私有组件。插件可以在编辑器上方或下方添加辅助行——例如状态 widget
+或快捷参考行——而不接触根布局、编辑器或焦点。行预算由 host 拥有:
+高度不足时先折叠低 importance 的 widget,编辑器永远存活。
+
+```ts
+service.register<InputWidget>('input.widget.below', {
+  id: 'my-widget',
+  order: 100,
+}, {
+  view: {
+    kind: 'text',
+    spans: [{ text: 'my-plugin ready', tone: 'success' }],
+  },
+})
+```
+
+自 M5 起,扩展面还覆盖注册表(计划 §10):
+
+- `registerCommand(contribution)` — 斜杠命令的**所有权**元数据
+  (`execution: 'local' | 'submission'`):插件声明的 local 命令始终直接
+  执行(永不被 busy-Enter 偏好 steer);submission 命令走会话投递策略。
+  实际执行仍在 host 的 commands 服务中;`/name args...` 保持 `rawInput`
+  原样。名称冲突被报告,绝不猜测。
+- `registerTheme(contribution)` — 一个具名语义调色板,可在 /settings
+  主题选择器中选择;owner 卸载时回退到内置调色板(选中的插件主题
+  绝不悬空)。
+- `registerSetting(contribution)` — 追加到 /settings 面板的设置行
+  (标签 + 当前值 + 选项 + 可选拒绝);面板由 host 拥有。
+- `registerAutocomplete(contribution)` — 自动补全 provider,在 host 自身
+  provider 返回 null 之后按确定性顺序咨询(逐 provider 隔离、
+  latest-only commit)。
+- `registerKeybinding(contribution)` — 归一化按键 → 语义动作的绑定,
+  由 host 的 InputRouter(M6)路由。插件用公开的 `NormalizedKey` 形状
+  (key + ctrl/alt/shift/super)声明按键和 host 动作列表中的语义动作
+  (`submit-draft`、`queue-draft`、`steer-draft`、`cancel-activity`、
+  `open-search`、`toggle-fullscreen`、`cycle-permission`)。host 统一归一化
+  所有终端输入(Kitty CSI-u、modifyOtherKeys、legacy 序列)——插件永远
+  看不到原始 escape 数据。保留的 host 生命周期按键(Ctrl+C/D/S/F/O/T/G/J、
+  Ctrl+Enter、Enter、Esc)不可被占用;纯可打印按键永不触发绑定(输入
+  永远优先);绑定是非捕获的,在优先级梯子的最后触发(question、approval、
+  overlay、编辑器之后)。动作通过 host 自己的路径执行——提交/会话安全
+  永不被绕过。
+- `registerMessageRenderer(contribution)` — TRANSCRIPT 消息渲染器(M7,
+  chain slot):接收语义 `MessagePresentationSnapshot`(不可变;绝不是可变
+  message 或容器),返回 `ExtensionView` 或 `undefined`(弃权 → 下一个
+  渲染器 → host 回退)。按 kind 限定的渲染器只作用于对应消息类型。
+- `registerToolRenderer(contribution)` — 工具卡片渲染器(M7,keyed slot):
+  从 `ToolPresentationSnapshot`(callId、toolName、status、arguments、
+  result、expanded)呈现一个工具名的卡片;winner(最低 priority)弃权后
+  落到下一个渲染器,再到 host 回退。同一工具名的 priority 平局是显式
+  错误。渲染器绝不会卡住 transcript:抛错的渲染器被隔离、链继续,
+  消息缓存内嵌渲染器身份 + 注册表 revision,因此 HMR/unload 只重建
+  受影响的组件。
+- `showOverlay(view, options)` — 受管 overlay 租约(M8):插件提供
+  `ExtensionView` + 尺寸提示;host 通过其 overlay broker 挂载(模态堆叠、
+  焦点、fullscreen 迁移)。返回的租约是 generation 限定的(表面最终
+  dispose 会关闭所有仍在持有的租约),close() 幂等,hide()/show() 切换
+  可见性而不关闭。插件永远不能挂载原始组件或抢焦点——终端和 overlay
+  栈由 host 拥有。
+[扩展 API v1 作者指南](docs/extension-api.md)记录了导入规则、完整
+surface 表、生命周期/渲染契约、M11 弃用策略与稳定性契约。
+
+M10 验收 fixture(计划 §15):仓库附带一个 vim-mode fixture
+(`test/fixtures/vim-plugin/`),用于验证编辑器扩展接缝——第三方 Cordis
+插件可消费打包后的公开 SDK,其替换编辑器通过**语义化** `EditorInputEvent`
+接收输入(绝不接触原始终端字节),编辑器的 `create()`/`dispose()` 正常
+工作——只导入 `@xmoon76/dsh-pi-tui/extensions`。它**不是**生产级 Vim,
+也**不是** Stable API 完整性的证明:模态模式行为(insert/normal)不属于
+Stable 契约,其余公开能力(命令、主题、设置、自动补全、按键绑定、渲染器、
+overlay、widget)都有各自的独立测试。它的 CI 门禁禁止 `@xmoon76/pi-tui`、
+`src/tui-app` 和仓库相对内部路径:如果 Stable 插件需要私有导入,说明 SDK
+缺 capability(没有 `unsafeGetTuiApp()` 逃生舱)。
+
+- `registerEditor(contribution)` — 编辑器 SDK(M9,计划 §14):按 priority
+  单选(平局是显式错误);winner 通过 host 的**原子交接**占据编辑器座席
+  (create → 转移 draft/cursor → mount → focus → dispose 旧编辑器)。
+  create 抛错时当前编辑器继续工作;winner 卸载恢复下一个 winner / host
+  默认编辑器,**保留 draft**。插件编辑器收到 `EditorHost`(surfaceId、
+  generation、getSnapshot、replaceText、语义动作 dispatch submit/
+  queue-submit/steer/open-external-editor、subscribe、invalidate)——但
+  host 仍然拥有 busy-Enter、Ctrl+Enter、local 命令分类、粘贴保护、
+  approval/question 捕获、会话 guard/lock、外部编辑器和退出:插件编辑器
+  永远不能绕过这些。
+
+生命周期由 host 拥有:插件 Cordis fiber 卸载(HMR、禁用)时注册自动清理,
+regular/fullscreen 都会刷新,`handle.invalidate()/replace()` 通过活动屏幕
+重渲染。`@xmoon76/dsh-pi-tui/builtins` 入口是仅 Loader 使用的一方贡献者
+(版本徽标、轮次/步骤计数器、todo 摘要 dock 项)——不是稳定的第三方
+SDK。原始终端访问、pre-host 输入拦截与完整输入所有权**不属于 Stable
+层级**(见 Advanced/Unstable 路线图)。
+
+## 斜杠命令(节选)
+
+- `/sessions [query]` — 打开会话选择器:对会话 id、标题和工作区进行
+  边输入边搜索,行按工作区分组并实时显示 `filtered/total` 计数,标题在
+  后台按需加载。回车切换到所选会话。
+- `/search <query>` — 在持久化的会话日志中全文搜索,然后跳转到命中项。
+- `/title [title]` / `/rename [title]` — 带参数时设置当前会话的标题
+  (固定标题,防止自动生成;标题会出现在 `/sessions` 选择器中);
+  **不带参数时根据对话重新生成标题——这会覆盖当前标题,包括你之前
+  固定的标题**。
+- `/yolo` — 切换到 `danger-full-access`(`/permission danger-full-access`
+  的别名)。
+- `/queue` — 逐条管理队列:编辑、删除、单条 steer,或向 agent 的 inbox
+  插入消息(编辑器上方的队列窗格显示待处理消息;`Ctrl+S` 一次性全部
+  steer,`Alt+↑` 把全部消息拉回编辑器)。
+- `/status` — 显示当前会话的统计与身份信息(回合数、token 用量、
+  工作区、已安装的 dsh 版本)。
+- `/preset`、`/model`、`/settings`、`/export`、`/fork`、`/subagents` —
+  见 `dsh --profile pi-tui` 的命令自动补全(`/` + Tab)。
+
+## 快捷键(节选)
+
+- `Ctrl+F` — 切换转录搜索(`/search <query>` 覆盖层;再按一次关闭)。
+- `Shift+Tab` — 循环切换权限预设(read-only → workspace-write →
+  danger-full-access);页脚的模式槽位会为每个预设显示徽章
+  (`[workspace-write]` / `[read-only]` / `[custom]`,`[yolo]` 标记免审批
+  模式)。
+- `Ctrl+S` — steer:有排队消息时,把整个队列(加上草稿,若有)一次性
+  送入正在运行的回合;否则只发送草稿。空闲的 agent 会用全部内容开启
+  新回合。
+- `Alt+↑` — 出队:把所有排队消息拉回编辑器草稿。
+- `Ctrl+T` — 切换完整待办列表;编辑器上方的 dock 始终显示待办摘要与
+  后台任务,排队的输入渲染在两者之间。
+- `@` — 编辑器中的文件/文件夹提及:`@` + Tab 从整个工作区补全文件
+  (`fd` 在 PATH 上时以其为后端,否则使用内置的递归回退)。字面
+  `@path` 会被提交,由模型自行读取文件。有后台工作时,空编辑器的 `↓`
+  或 `Ctrl+J` 会打开覆盖两种表面的任务浏览器:
+  - **子代理行**(可继续的实时子任务)——`Enter` 以只读方式打开子代理
+    的转录(`Esc` 返回);它们从不注册 job 记录,所以此浏览器是它们唯一
+    可一览的归宿。
+  - **job 行**(bash 与一次性子代理 job)——`Enter` 只显示状态查看器:
+    bash job 的输出读取游标属于模型的 `job_output`,而一次性子代理 job
+    记录不带子会话 id,因此转录需通过 `/subagents` 访问(`s` 停止 job)。
+  只要有后台工作处于活动状态,页脚徽章就会显示
+  `[N tasks running · M agents · ↓ view]`。
+
+## 启动选项
+
+TUI 的启动行新增了 `--preset <id>`——新会话启动时使用的 agent 预设
+(回退到 `$DSH_PI_TUI_PRESET`,然后是保存的设置默认值)。它存在的原因是
+`/preset` 只对空白(尚未创建)会话生效,所以启动时选择是选择预设的
+另一半。其余标志都是 dsh runner 自有的(`--session <id>`,……)。
+
+## 会话生命周期
+
+不带 `--session` 打开 TUI **不会创建任何会话**:第一条用户消息(文本、
+斜杠命令、`Ctrl+S` steer 或 `!` shell)才会惰性启动会话。`--session <id>`
+仍然立即恢复会话,本地 `!!` 命令无需会话即可运行。
+
+## 在 P0 spike 中验证过的事项
+
+- 内置 pi-tui:fork 自带的套件在 `node --test` 下通过(每次重新
+  vendor 后把它作为同步门禁运行;计数特意不抄在这里——
+  `packages/pi-tui/package.json` 是版本事实的唯一来源)。
+- `TuiApp` 能在 headless xterm 上渲染、接受编辑器输入并处理 Ctrl+C。
+- 整个导入链(pi-tui、tui-app、`@deepseek-ai/dsh-cmdline`、commander)
+  能在 tsx ESM 钩子下加载——即 dsh 源码启动契约。
+- 原生修饰键扩展是可选的:在 Linux 上加载器返回 `undefined` 而不尝试
+  加载,非 TTY 的 stdin 路径有守卫。
+
+## 诊断日志
+
+TUI 把自身诊断写到 stderr 和一个日志文件(`ctx.logger` 在此进程中不可见
+——没有 exporter):
+
+- 默认文件:`$DSH_HOME/logs/pi-tui-<pid>.log`(默认 `~/.dsh/logs/`);
+- 行格式:`[tui] <ISO time> <level> <message> k=v ...`;
+- 默认级别 `info`:只记录关键生命周期事件(启动/恢复/切换/退出、
+  跨进程 guard 警告、错误);`debug` 额外记录每次发送前的 guard 检查。
+
+配置(环境变量):
+
+| 变量 | 含义 | 默认值 |
+|---|---|---|
+| `DSH_PI_TUI_LOG` | 日志文件路径;`off` 关闭文件日志 | `$DSH_HOME/logs/pi-tui-<pid>.log` |
+| `DSH_PI_TUI_LOG_LEVEL` | `debug` / `info` / `warn` / `error` | `info` |
+
+排障示例:
+
+```sh
+DSH_PI_TUI_LOG_LEVEL=debug dsh --profile pi-tui
+tail -f ~/.dsh/logs/pi-tui-*.log
+```
+
+## 安全与运维说明
+
+- **每个会话只有一个界面。** dsh 没有跨进程的会话协调:一个会话同时
+   在两个 dsh 进程中打开(TUI + web,或两个 TUI)会损坏其日志。TUI 会
+   拒绝打开已被另一个存活 dsh 进程持有的会话(日志旁的 `owner.lock`
+   文件,带 pid/starttime 探测以处理崩溃残留的陈旧锁——第二个界面在
+   **打开时**就被阻止,而不是在损坏发生之后)。对于写入,TUI 会检测到
+   另一个写入者并阻止发送;再次按下同一个操作(Enter 提交、Ctrl+S
+   steer,草稿不变)会强制通过——编辑过的草稿、换过的按键、新的文件
+   修订或会话切换都会使强制失效。绝不要在一个会话上运行两个界面
+   (完整契约:`docs/concurrency.md`)。
+- **会话修复。** `node_modules/@xmoon76/dsh-pi-tui/scripts/repair-session.mjs`
+  修复损坏的日志(`--scan` 只读列出损坏;`--yes` 应用修复并强制备份)。
+  撕裂(截断)的尾部会在最后一个完整帧处截断,并报告精确的字节核算;
+  指向重复 seq 的引用绝不自动解决——修复会拒绝并要求
+  `--duplicate-reference=first|last|segment`。修复后的日志在备份被认为
+  多余之前,会用 dsh 读取器自身的布局检查重新验证。(完整修复契约,
+  包括帧布局约束:`docs/repair-session.md`。)
+- **退出。** `/exit`(`/quit` 的别名)以 10 秒硬超时刷新会话:卡死的
+  提供方无法困住 TUI。如果刷新失败或超时,终端会打印警告(尾部可能
+  未持久化),进程仍然退出。
+- **性能。** `scripts/bench.mts`(非默认)测量摄取、投影、冷/热重建、
+  流式帧、主题切换与堆;保存的基线见 `docs/perf-baseline.md`。未变化的
+  转录消息会复用其渲染组件,因此热路径的每帧重建不会随历史增长。
+
+## 许可证
+
+MIT。`packages/pi-tui` 保留其上游 MIT 许可证与作者署名
+(Copyright (c) 2025 Mario Zechner;Moonshot AI fork)。

package/dist/builtins.mjs

@@ -1,5 +1,5 @@
 import { TUI_STARTUP_SERVICE } from "./startup.mjs";
-import { M as PI_TUI_EXTENSIONS_SERVICE } from "./src-AgdnRnGA.mjs";
+import { M as PI_TUI_EXTENSIONS_SERVICE } from "./src-C_RdKmcj.mjs";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 //#region src/builtins.ts

package/dist/extensions.mjs

@@ -1,3 +1,3 @@
 import "./startup.mjs";
-import { A as inject, M as PI_TUI_EXTENSIONS_SERVICE, N as API_VERSION, P as describeKey, j as name, k as apply } from "./src-AgdnRnGA.mjs";
+import { A as inject, M as PI_TUI_EXTENSIONS_SERVICE, N as API_VERSION, P as describeKey, j as name, k as apply } from "./src-C_RdKmcj.mjs";
 export { API_VERSION, PI_TUI_EXTENSIONS_SERVICE, apply, describeKey, inject, name };

package/dist/index.mjs

@@ -1,3 +1,3 @@
 import "./startup.mjs";
-import { C as shouldConsumeAdvertisedMiss, D as subagentNoticeIsFailure, E as subagentJobViewHint, O as forkSeed, S as runningProfile, T as subagentJobTranscriptId, _ as name, a as SessionLockRefusedError, b as resolveInitialCatalog, c as compactingFromLog, d as foldCompactionEvent, f as foldQueueRows, g as matchPendingSubagentCall, h as isSubagentSettlementNotice, i as SESSIONLESS_COMMANDS, l as composeAgent, m as isPlainExitPrompt, n as HOST_COMMAND_CATALOG, o as apply, p as inject, r as LOCAL_COMMANDS, s as busyAfterTurnBoundary, t as Config, u as dangerCommand, v as recomposeBlank, w as shouldSteerOnEnter, x as resumeCommand, y as recordedPreset } from "./src-AgdnRnGA.mjs";
+import { C as shouldConsumeAdvertisedMiss, D as subagentNoticeIsFailure, E as subagentJobViewHint, O as forkSeed, S as runningProfile, T as subagentJobTranscriptId, _ as name, a as SessionLockRefusedError, b as resolveInitialCatalog, c as compactingFromLog, d as foldCompactionEvent, f as foldQueueRows, g as matchPendingSubagentCall, h as isSubagentSettlementNotice, i as SESSIONLESS_COMMANDS, l as composeAgent, m as isPlainExitPrompt, n as HOST_COMMAND_CATALOG, o as apply, p as inject, r as LOCAL_COMMANDS, s as busyAfterTurnBoundary, t as Config, u as dangerCommand, v as recomposeBlank, w as shouldSteerOnEnter, x as resumeCommand, y as recordedPreset } from "./src-C_RdKmcj.mjs";
 export { Config, HOST_COMMAND_CATALOG, LOCAL_COMMANDS, SESSIONLESS_COMMANDS, SessionLockRefusedError, apply, busyAfterTurnBoundary, compactingFromLog, composeAgent, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, isPlainExitPrompt, isSubagentSettlementNotice, matchPendingSubagentCall, name, recomposeBlank, recordedPreset, resolveInitialCatalog, resumeCommand, runningProfile, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure };

package/dist/{src-AgdnRnGA.mjs → src-C_RdKmcj.mjs}

@@ -1841,7 +1841,7 @@ const markdownTheme = {
 	underline: (text) => chalk.underline(text)
 };
 //#endregion
-//#region ../pi-tui/dist/index.mjs
+//#region packages/pi-tui/dist/index.mjs
 function fuzzyMatch(query, text) {
 	const queryLower = query.toLowerCase();
 	const textLower = text.toLowerCase();

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@xmoon76/dsh-pi-tui",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The dsh-pi-tui bundle: a TUI surface for DeepSeek Harness profiles (dsh --profile pi-tui)",
   "license": "MIT",
   "author": "XMoon <xmoonox@gmail.com>",
   "homepage": "https://github.com/XMoon/dsh-pi-tui#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/XMoon/dsh-pi-tui.git",
-    "directory": "packages/dsh-pi-tui"
+    "url": "git+https://github.com/XMoon/dsh-pi-tui.git"
   },
   "bugs": {
     "url": "https://github.com/XMoon/dsh-pi-tui/issues"
@@ -58,6 +57,7 @@
     "scripts",
     "cordis.patch.yml",
     "README.md",
+    "README.zh-CN.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -141,23 +141,33 @@
     "@deepseek-ai/dsh-attachment": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-brand": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.8"
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.8",
+    "tsx": "^4.23.12"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": "^22.19.0 || >=24"
   },
   "scripts": {
-    "build": "tsdown",
-    "build:package": "pnpm --dir ../pi-tui build && pnpm build",
-    "typecheck": "pnpm build:package && tsc -p tsconfig.json --noEmit",
-    "test": "pnpm build:package && node --test test/*.test.ts test/*.test.mjs",
     "clean": "rm -rf dist",
+    "clean:fork": "pnpm --dir packages/pi-tui clean",
+    "build:fork": "pnpm --dir packages/pi-tui build",
+    "build:bundle": "tsdown",
+    "build": "pnpm build:fork && pnpm build:bundle",
+    "typecheck:fork": "pnpm --dir packages/pi-tui typecheck",
+    "typecheck:bundle": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "pnpm typecheck:fork && pnpm typecheck:bundle",
+    "test:fork": "pnpm --dir packages/pi-tui test",
+    "test:bundle": "node --test test/*.test.ts test/*.test.mjs",
+    "test:docs": "node --test docs/tmux/*.test.mjs",
+    "test": "pnpm test:fork && pnpm test:bundle && pnpm test:docs",
     "smoke": "node scripts/tarball-smoke.mjs",
     "smoke:fixture": "node scripts/extension-fixture-smoke.mjs",
     "smoke:advanced": "node scripts/advanced-plugin-smoke.mjs",
     "smoke:phase4": "node scripts/phase4-plugin-smoke.mjs",
     "smoke:unstable": "node scripts/unstable-plugin-smoke.mjs",
+    "smoke:vim": "node scripts/vim-plugin-smoke.mjs",
     "smoke:examples": "node scripts/examples-plugin-smoke.mjs",
-    "smoke:vim": "node scripts/vim-plugin-smoke.mjs"
+    "pack:release": "rm -f xmoon76-dsh-pi-tui-*.tgz && pnpm pack --pack-destination .",
+    "smoke:pack": "node scripts/tarball-smoke.mjs"
   }
 }

package/scripts/naming-gate.mjs

@@ -14,7 +14,9 @@ import { spawnSync } from 'node:child_process'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..')
+// The repository root IS the @xmoon76/dsh-pi-tui package root (root-package
+// migration): scripts/ sits directly under it.
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
 const failures = []
 const checks = []
 
@@ -28,35 +30,34 @@ function readJson(path) {
 }
 
 const rootPkg = readJson(join(ROOT, 'package.json'))
-const bundlePkg = readJson(join(ROOT, 'packages', 'dsh-pi-tui', 'package.json'))
 const forkPkg = readJson(join(ROOT, 'packages', 'pi-tui', 'package.json'))
 
 // 1. Repository + profile naming: never the reserved `tui` / `dsh-tui` family.
-check('root package name is dsh-pi-tui', rootPkg.name === 'dsh-pi-tui', rootPkg.name)
+check('root package name is @xmoon76/dsh-pi-tui', rootPkg.name === '@xmoon76/dsh-pi-tui', rootPkg.name)
 check('no @deepseek-ai/dsh-tui anywhere', !['@deepseek-ai/dsh-tui', 'dsh-tui'].some(name =>
-  [rootPkg, bundlePkg, forkPkg].some(pkg => pkg.name === name)))
-for (const pkg of [rootPkg, bundlePkg, forkPkg]) {
+  [rootPkg, forkPkg].some(pkg => pkg.name === name)))
+for (const pkg of [rootPkg, forkPkg]) {
   const manifest = JSON.stringify(pkg)
   if (manifest.includes('@deepseek-ai/dsh-tui') || manifest.includes('"dsh-tui"')) {
     check(`no dsh-tui references in ${pkg.name}`, false)
   }
 }
 // The startup service keeps its stable id (internal Loader ids, fine as-is).
-const patch = readFileSync(join(ROOT, 'packages', 'dsh-pi-tui', 'cordis.patch.yml'), 'utf8')
+const patch = readFileSync(join(ROOT, 'cordis.patch.yml'), 'utf8')
 check('patch rows keep tui-startup/tui-app ids', patch.includes('id: tui-startup') && patch.includes('id: tui-app'))
 check('startup service keeps TUI_STARTUP_SERVICE',
-  readFileSync(join(ROOT, 'packages', 'dsh-pi-tui', 'src', 'startup.ts'), 'utf8').includes("export const TUI_STARTUP_SERVICE = 'tuiStartup'"))
+  readFileSync(join(ROOT, 'src', 'startup.ts'), 'utf8').includes("export const TUI_STARTUP_SERVICE = 'tuiStartup'"))
 
-// 2. Package roles: the fork is private + bundled; the bundle is public.
+// 2. Package roles: the fork is private + bundled; the root bundle is public.
 check('fork package is private (@xmoon76/pi-tui)', forkPkg.private === true, `private=${String(forkPkg.private)}`)
-check('bundle package is public (@xmoon76/dsh-pi-tui)', bundlePkg.private !== true, `private=${String(bundlePkg.private)}`)
-check('bundle declares dsh.bundle.patch', bundlePkg.dsh?.bundle?.patch !== undefined, bundlePkg.dsh?.bundle?.patch)
+check('root bundle package is public (@xmoon76/dsh-pi-tui)', rootPkg.private !== true, `private=${String(rootPkg.private)}`)
+check('root bundle declares dsh.bundle.patch', rootPkg.dsh?.bundle?.patch !== undefined, rootPkg.dsh?.bundle?.patch)
 
 // 3. The fork is bundled, never a runtime dependency of the published package.
-const tsdown = readFileSync(join(ROOT, 'packages', 'dsh-pi-tui', 'tsdown.config.ts'), 'utf8')
+const tsdown = readFileSync(join(ROOT, 'tsdown.config.ts'), 'utf8')
 check('tsdown deps.onlyBundle includes @xmoon76/pi-tui',
   tsdown.includes("onlyBundle") && tsdown.includes("'@xmoon76/pi-tui'"))
-const runtimeDeps = bundlePkg.dependencies ?? {}
+const runtimeDeps = rootPkg.dependencies ?? {}
 check('@xmoon76/pi-tui is NOT a runtime dependency of the bundle',
   !(runtimeDeps['@xmoon76/pi-tui'] !== undefined), runtimeDeps['@xmoon76/pi-tui'] ?? 'absent')
 const forkDeps = forkPkg.dependencies ?? {}
@@ -68,14 +69,17 @@ check('fork repository.note records the vendored commit (single source of truth)
   forkPkg.repository?.note ?? 'missing')
 
 // 5. The tarball smoke + pack gate stay wired (stage G).
-check('bundle prepack gate exists', (bundlePkg.scripts?.prepack ?? '').includes('build:package'))
-check('bundle postpack smoke exists', (bundlePkg.scripts?.postpack ?? '').includes('tarball-smoke'))
+check('bundle prepack gate exists', (rootPkg.scripts?.prepack ?? '').includes('pnpm build'))
+check('bundle postpack smoke exists', (rootPkg.scripts?.postpack ?? '').includes('tarball-smoke'))
+check('postpack keeps the pluginization smokes',
+  ['extension-fixture-smoke', 'vim-plugin-smoke', 'examples-plugin-smoke'].every(name =>
+    (rootPkg.scripts?.postpack ?? '').includes(name)))
 
 // 6. The workspace has no stray dist/ or tarballs COMMITTED (dist is
 //    gitignored by design; the gate checks git tracking, not the tree).
-for (const pkg of ['pi-tui', 'dsh-pi-tui']) {
-  const tracked = spawnSync('git', ['ls-files', `packages/${pkg}/dist`], { cwd: ROOT, encoding: 'utf8' }).stdout.trim()
-  check(`packages/${pkg}/dist is not committed`, tracked === '', tracked.split('\n').filter(Boolean).slice(0, 3).join(', '))
+for (const [label, path] of [['root dist', 'dist'], ['packages/pi-tui/dist', 'packages/pi-tui/dist']]) {
+  const tracked = spawnSync('git', ['ls-files', path], { cwd: ROOT, encoding: 'utf8' }).stdout.trim()
+  check(`${label} is not committed`, tracked === '', tracked.split('\n').filter(Boolean).slice(0, 3).join(', '))
 }
 const tgz = spawnSync('git', ['ls-files', '*.tgz'], { cwd: ROOT, encoding: 'utf8' }).stdout.trim()
 check('no tarballs committed', tgz === '', tgz.split('\n').filter(Boolean).slice(0, 3).join(', '))
@@ -103,7 +107,7 @@ for (const workflow of ['ci.yml', 'release.yml']) {
 //    crashes). `dsh-session-query` was removed by this rule: the picker
 //    types it structurally (src/sessions.ts) and reads the service off the
 //    live context, so it never needed the package.
-const bundleSrc = join(ROOT, 'packages', 'dsh-pi-tui', 'src')
+const bundleSrc = join(ROOT, 'src')
 const srcFiles = (() => {
   const out = []
   const walk = (dir) => {
@@ -126,7 +130,7 @@ for (const file of srcFiles) {
   // package that is ONLY read this way (never imported) has no place in
   // the peer list — same rule as dsh-session-query.
 }
-const peers = new Set(Object.keys(bundlePkg.peerDependencies ?? {}))
+const peers = new Set(Object.keys(rootPkg.peerDependencies ?? {}))
 for (const imported of [...srcImports].sort()) {
   check(`peer declared for src import ${imported}`, peers.has(imported), peers.has(imported) ? '' : 'missing from peerDependencies')
 }
@@ -135,6 +139,16 @@ for (const peer of [...peers].sort()) {
   check(`peer ${peer} is imported by src/`, srcImports.has(peer), srcImports.has(peer) ? '' : 'no import in src/ (dead peer)')
 }
 
+// 9. The M0–M11 pluginization contract survives the root-package migration:
+//    the public SDK subpaths and their tsdown entries must all stay present.
+const exportsMap = rootPkg.exports ?? {}
+for (const subpath of ['./extensions', './extensions/advanced', './extensions/unstable', './builtins']) {
+  check(`exports keep ${subpath}`, exportsMap[subpath] !== undefined)
+}
+for (const entry of ['src/extensions.ts', 'src/builtins.ts', 'src/extension/advanced.ts', 'src/extension/unstable.ts']) {
+  check(`tsdown entry keeps ${entry}`, tsdown.includes(entry))
+}
+
 for (const line of checks) console.log(line)
 if (failures.length > 0) {
   console.error(`\nnaming-gate FAILED (${failures.length}):`)

package/scripts/tarball-smoke.mjs

@@ -180,7 +180,9 @@ function main() {
     // the generic patterns: its source deliberately assembles the old
     // /home/xmoon/ marker at runtime (the literal would otherwise trip the
     // check on its own file). The dynamic-root checks still apply to it.
-    const repoRoot = realpathSync(join(SCRIPT_DIR, '..', '..', '..'))
+    // After the root-package migration the repository root IS the package
+    // root, so both resolve from SCRIPT_DIR with a single `..`.
+    const repoRoot = realpathSync(join(SCRIPT_DIR, '..'))
     const packageRoot = realpathSync(PACKAGE_ROOT)
     // The bundle dist may be absent (a smoke run on a raw checkout); the
     // structure checks below already fail loudly for that, so never crash