@fishwithcat/dsh-tui-app 0.0.0-stage → 0.2.2-alpha.3.fork.1

package/README.i18n.yaml

@@ -0,0 +1,79 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/bundle/tui-app/README.md
+/:
+  en: 5ef521aafc9f2218
+  zh: 1c48c446b495c0c5
+/deepseek-ai-dsh-tui-app:
+  en: 6a23ca8f9a47405e
+  zh: b64330cf6abe3c84
+/deepseek-ai-dsh-tui-app/summary:
+  en: ac1ac8f5faa37243
+  zh: a1315993460c7fd3
+/deepseek-ai-dsh-tui-app/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-tui-app/use-this-package:
+  en: 88c14b005e03bf78
+  zh: 0b9ad8bc5a690a3c
+/deepseek-ai-dsh-tui-app/use-this-package/composing-prompting-and-interrupting:
+  en: 34da0bc57f324c76
+  zh: 7ca36d67e490aeaf
+/deepseek-ai-dsh-tui-app/use-this-package/watching-a-subagent:
+  en: 06e52609345e4e25
+  zh: fde80695a5359b03
+/deepseek-ai-dsh-tui-app/use-this-package/commands:
+  en: 39e96c52dda57e65
+  zh: d2aade8d44940539
+/deepseek-ai-dsh-tui-app/use-this-package/local-shell-commands:
+  en: b410979abef87262
+  zh: 8951a763c4054fc5
+/deepseek-ai-dsh-tui-app/use-this-package/settings:
+  en: 091f286d20d6c617
+  zh: 626a2a502fe56357
+/deepseek-ai-dsh-tui-app/understand-the-implementation:
+  en: a7daa7d1183a433f
+  zh: 8abbd0d3ec08a8d6
+/deepseek-ai-dsh-tui-app/understand-the-implementation/rendering:
+  en: 5acabadd3a7a501d
+  zh: de3908c848d3d1fa
+/deepseek-ai-dsh-tui-app/understand-the-implementation/interaction-seams:
+  en: ad6ba4563696862a
+  zh: 469b082552af2e27
+/deepseek-ai-dsh-tui-app/understand-the-implementation/clipboard-images:
+  en: 56fdbc5555bed800
+  zh: 47631ee2be590508
+/deepseek-ai-dsh-tui-app/understand-the-implementation/patch-surface-over-base:
+  en: d36899ca12702771
+  zh: ef9c1a87b54bc693
+/deepseek-ai-dsh-tui-app/understand-the-implementation/source-map:
+  en: bcc8357828fac133
+  zh: 8da9879fda2c2fa7
+/deepseek-ai-dsh-tui-app/understand-the-implementation/invariant-ownership:
+  en: a6fef7da2427069c
+  zh: f8d93f6061eac13b
+/deepseek-ai-dsh-tui-app/further-exploration:
+  en: c0641a758f0b6fc2
+  zh: ed75683ed4106e50
+/deepseek-ai-dsh-tui-app/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-tui-app/model-experience/interactive-coding-session:
+  en: 75fef2974a28ed59
+  zh: 2a8e0a3bf5701745
+/deepseek-ai-dsh-tui-app/model-experience/interactive-coding-session/what-the-model-sees:
+  en: 1f37caa3b5a79ed2
+  zh: bfff24eb1b72fae3
+/deepseek-ai-dsh-tui-app/model-experience/interactive-coding-session/token-effect:
+  en: 7260a205dc748857
+  zh: f3fd6cb26fff8aa8
+/deepseek-ai-dsh-tui-app/model-experience/interactive-coding-session/kv-cache-effect:
+  en: 113a1ddb9516cf95
+  zh: d852ea1f4d1dc176
+/deepseek-ai-dsh-tui-app/known-limitations-and-deferred-work:
+  en: 451f6913260e119c
+  zh: 0b6fa8bbdb79f07a
+/deepseek-ai-dsh-tui-app/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,246 @@
-# Temporary Holding Version
+---
+description: "Interactive terminal UI for dsh: one Agent, one session, driven in-process from a full-screen terminal surface, for users working over SSH or preferring a terminal to the browser."
+kind: "package-bundle"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-tui-app
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-tui-app` is dsh's interactive terminal surface. Run `dsh` and one Agent starts in the current directory with the shared model, sandbox, and approval defaults, and the base tools plus `apply_patch` — but rendered as a full-screen terminal application: a scrolling transcript, a composer above a pinned footer, and status lines that report the workspace, context occupancy, routed model, token throughput, total tokens, cache-hit rate, and the delegated-subagent count. A loopback watch service lets another terminal read a local subagent's transcript and live stream without a second Agent. The main boundary: one session per invocation, with no browser or file sidebar.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Open the terminal UI from the directory that should be the workspace:
+
+```sh
+dsh
+```
+
+`dsh` with no profile boots this bundle; `dsh --profile tui` names it explicitly and takes the same flags. `DSH_DEFAULT_PROFILE` selects a different default for a bare invocation (`DSH_DEFAULT_PROFILE=web dsh`), and an empty value restores the upstream requirement that every launch name its profile. The app refuses to start without an interactive terminal, so a piped or redirected invocation fails loudly instead of waiting for keys it cannot read.
+
+### Composing, prompting, and interrupting
+
+Type a prompt and press Enter. While the Agent works, the composer switches to steering: an Enter submits text the running turn consumes at its next step, and Esc interrupts the turn together with every live subagent descendant the session delegated to. Delegated work outlives the Agent's own turn, so the footer keeps reporting `running` and the composer keeps offering the cancel keys while a subagent is still inside a turn. A manual `/compact` runs outside the turn lifecycle, so while the summary is generated the footer replaces `idle` with `compacting`, and then reports the settled result as a notice. PageUp/PageDown, the mouse wheel, and terminal search scroll the transcript without leaving the app; the status bar reports when the view has scrolled away from the newest row.
+
+In alternate-screen mode, dragging to select text copies it automatically on release. Local macOS sessions use `pbcopy`, including in Terminal.app; a failed write displays `Copy failed`. Other platforms and SSH sessions require terminal support for OSC 52 clipboard writes, whose success cannot be confirmed. Command+C copies the selection again when the terminal forwards that key. If the terminal intercepts Command+C, use its native selection gesture (often Option-drag on macOS), then Command+C; native selection also handles copying in inline mode. Ctrl+C retains its interrupt/exit behavior.
+
+Press Ctrl+V to attach the image on the system clipboard to the draft. The composer shows every held image as an `[Image #1]` marker, which behaves like typed text: moving or deleting a marker moves or drops its image. The paste reads the clipboard directly, so the terminal's own text paste keeps its usual key. While that read is in flight the footer reports `pasting image…`, so a slow platform reader never looks frozen.
+
+Press Shift+Tab to toggle plan mode for the session's Agent. While plan mode is on, the footer marks it with `plan` beside the lifecycle state and the empty composer lists the key. A toggle made while a turn is running applies from the next step, exactly as `/plan` does; a deployment that mounts no plan mode reports it instead of changing the session. When the agent finishes planning it presents the plan through `exit_plan_mode`, and the review shows that plan as markdown above the Approve / Keep planning choice, taking the rows above the pinned composer and footer so a long plan reads on any terminal size, scrollable with the arrows, PageUp/PageDown, and the wheel, because the plan-mode policy routes the plan through the tool rather than a plain reply. Choosing Keep planning leaves plan mode active and hands the turn back, so the agent waits for your next message instead of revising the plan immediately.
+
+| Key | Action |
+|---|---|
+| `Enter` | Submit the prompt, or steer the running turn |
+| `Esc` | Interrupt the running turn and the session's live subagents; at a prompt, skip the question |
+| `Shift+Tab` | Toggle plan mode |
+| `Ctrl+V` | Attach the image on the system clipboard to the draft (`Alt+V` on Windows and WSL, where the terminal owns Ctrl+V) |
+| `Ctrl+C` | Cancel the running turn and the session's live subagents, or stop a local `!` command; at a prompt, cancel the whole ask; with neither working, exit |
+| `Ctrl+D` | Exit |
+| `PageUp` / `PageDown` | Scroll the transcript, or a question's overflowing detail |
+| `Up` / `Down` | Scroll a question's overflowing detail; otherwise move its picker |
+| `Left` / `Right` | Move a picker's selection while a question's detail owns the arrows |
+| `Space` | Check or uncheck an option in a multi-select question |
+| `Ctrl+L` | Repaint from scratch |
+
+Exiting — Ctrl+C with nothing running, Ctrl+D, or `/quit` — restores the terminal and prints the session id as a `dsh-tui --resume <session-id>` command, so a later invocation continues the same conversation. Resuming — that command at startup, or `/resume` in the composer — restores the stored conversation into the transcript before the composer accepts the next prompt, so the earlier prompts, replies, and Tool rows are back on screen instead of only their effects on the model. The `/resume` picker and `/sessions` label each stored session with its title — the leading words of the first human message, a generated title, or an explicit rename — beside its id, start time, and workspace. The hint is printed only where the deployment mounts a session-persistence backend; without one there is nothing for `--resume` to open.
+
+### Watching a subagent
+
+When a local subagent starts, the TUI publishes a loopback connection record and then prints a watch command as an ordinary notice:
+
+```
+· watch: dsh-tui watch <session-id>
+```
+
+The `--watch <session-id>` application flag is equivalent.
+
+`/subagents` opens a pinned panel listing the session's delegated descendants through the subagent service, each with its activation state and the exact watch command. The read reaches stored children as well as resident ones, and a child catalog it cannot read appears as a diagnostic row. The panel refreshes when a catalog fact or lifecycle edge lands, so children that start or settle while it is open join or leave the list; the list never writes a transcript row, and the main Agent keeps streaming underneath without moving it. Up and Down or PageUp and PageDown scroll a list taller than the panel, and Enter, Esc, or Ctrl+C closes it without cancelling the Agent.
+
+Run that command in another terminal to follow the child. The viewer is read-only: it has no composer and does not send prompts, approve Tools, or cancel the child. It shows the committed transcript plus the text, reasoning, Tool calls, and approval audit rows currently streaming, so opening it in the middle of a response shows the prefix already generated. PageUp/PageDown, the mouse wheel, selection copy, the palette, and the configured screen mode behave as they do in the interactive surface. Esc, Ctrl+C, and Ctrl+D only leave the viewer. Completing a model response keeps the connection open. A finished execution keeps its screen and the stream stays open for a later execution of the same child; a lost connection keeps the last trusted screen and reports the disconnect instead of reconnecting.
+
+A blank line and a horizontal rule separate the transcript from the footer. The footer names the child session id, its execution state, and the connection state: `online`, `history`, or `disconnected`. Its second line shows available context occupancy, decode throughput, total billed tokens, and cache-hit share from the child's committed events, in both online and history modes; disconnecting preserves the last figures. When no live service is published, or the published service is gone, the viewer opens the stored log through the persistence read handle and marks `history`; it takes no write lock, restores no Agent, and issues no model request. A bad token, an incompatible protocol, or a corrupt record is reported rather than silently downgraded to history. Both terminals must use the same user, the same `$DSH_HOME`, and compatible TUI persistence settings.
+
+### Commands
+
+A line beginning with a known `/command` runs that command instead of reaching the model. Other slash text reaches the Agent unchanged: `/ponytail full` invokes an installed user-invocable skill through the shared skill loader, while unknown skill names remain ordinary text. App commands and registered commands take precedence over skills with the same name. The app owns the session commands below; every other registered command — `/compact`, `/goal`, `/plan`, and deployment-provided commands — is discovered from the command registry and dispatched against the live Agent.
+
+| Command | Effect |
+|---|---|
+| `/help` | List the app's commands and every registered command |
+| `/new` | Flush the session, start a fresh one, then close the previous |
+| `/sessions` | List stored sessions by title, newest first |
+| `/subagents` | Open a pinned, live panel of delegated children with their activation state and watch command |
+| `/resume [id]` | Resume a stored session by id, or choose one from a picker; naming the live session keeps it |
+| `/model [provider/model]` | Choose a model from the live catalog, or switch directly |
+| `/effort [id]` | Choose the routed model's declared reasoning effort, or switch directly |
+| `/questions` | Answer a question whose foreground window closed, from the picker of calls still waiting |
+| `/quit` | Exit |
+
+### Local shell commands
+
+A line beginning with `!` runs locally instead of reaching the Agent: `!git status` executes through the mounted shell executor under the same sandbox policy as the agent's `bash` tool, without an approval prompt. Each line is a fresh shell in the session's working directory, so `cd` and exported variables do not carry to the next line. The command asks for the executor's upper bound (600 seconds by default), and output beyond the per-stream cap stays a tail whose spill file the row names. The footer reads `● shell` while it runs.
+
+The row is local only. Its command and output never enter the session log, are never sent to the model, and disappear on `/new`, `/resume`, and exit, so a later turn cannot cite them. `\!ls` sends the literal text `!ls` to the Agent instead.
+
+One local command runs at a time: while it runs, the composer refuses prompts and further `!` lines and keeps the draft, and while a turn or a compaction runs a `!` line is refused the same way. Ctrl+C stops the running command, keeps the output it already produced, and leaves the turn alone; the closing line reports `[exit code: N]`, `[cancelled]`, or `[timed out after 600s]`, and a sandbox denial names the mode that blocked it. Slash commands still run while a local command works. A deployment that mounts no shell executor refuses `!` lines and says so.
+
+### Settings
+
+The app's only deployment settings select where it draws and which palette it uses:
+
+| Field | Default | Meaning |
+|---|---|---|
+| `screen` | `'alternate'` | `'alternate'` draws the transcript in the alternate screen with the app's own scroll window; `'inline'` draws into the normal screen and leaves history to the terminal's scrollback. |
+| `colorScheme` | `'auto'` | Palette selection. `'auto'` reads the terminal's exported background signal and otherwise stays dark; `'dark'` and `'light'` pin the palette. |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tui-app) is the exhaustive source for every accepted field and its JSDoc. `DSH_TUI_SCREEN` and `DSH_TUI_COLOR_SCHEME` in the bundle patch supply the defaults.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The app owns one `TuiSession` and one terminal UI. It waits for the complete composition (`ctx.get('loader')?.await()`) so the Agent's scoped tools and adapters are mounted, creates or resumes the Agent through the core registry, and then subscribes to the durable `session/event` log, the live `agent/assistant-stream` feed, `agent/status`, and the `subagent/start` / `subagent/end` edges that report delegated work the footer and cancel keys follow. A resumed session's earlier events predate those subscriptions, so the app reads them back from the persistence backend through [`TuiSession.history()`](src/session.ts) — stopping at the Session's first live sequence so an event appended after resume is not folded twice — and folds them into the transcript before accepting input; an event that lands while that read is in flight is buffered and applied after the stored rows, keeping log order.
+
+While the renderer owns the terminal, console writes from mounted plugins are captured and appended as ordinary notice rows. A raw write would land on the row under the cursor, and the differential renderer would leave it there until that row's own content changed.
+
+### Rendering
+
+[`src/transcript.ts`](src/transcript.ts) folds those events into ordered rows — prompts, assistant messages, retained reasoning, Tool calls with their settled outcome, approval decisions, and app notices — and invalidates its rendered lines through a revision counter, while the view re-renders only the rows that revision changed: it caches each row's lines by row identity and viewport width, so a streamed delta renders the live row alone instead of the whole transcript. A prompt renders its image markers before its text, one marker per attached image in content order, because the terminal has no thumbnail and the durable content blocks are the record of what was attached. Message rows mark their role on the first line: a prompt opens with `›` and an assistant message with `◆`, in that role's color, while every later line aligns under a two-space indent. The first-line glyphs keep the roles apart even without color, and no rule is drawn into the continuation lines, so copying a reply does not drag a vertical bar along. Injected context is model input rather than conversation, so it produces a row only when its producer declared a one-line `notice` form: a workspace-instruction, skill-catalog, or runtime-context message stays in the session log, while a model switch, a plan-mode change, or a goal appears as an app notice. The footer sits under the composer in both screen strategies and occupies two lines: the workspace and Agent state right-aligned against the routed model and its reasoning effort, then the occupancy of the next request against the routed model's capacity, with the whole log's token figures at the bottom-right edge. Once the session has delegated any child, the occupancy is followed by a `● subagents (running/total)` marker — `●` while a child activation runs, `○` once every recorded child has settled — read from the same catalogs `/subagents` lists, and shown alone on a frame that knows no occupancy yet. Those figures are the decode throughput in tokens per second, the billed prompt-plus-output total, and the cache-read share of billed prompt tokens; each is omitted until it has data, the rate is the whole-log average the Web stats strip reports rather than a live instantaneous one, and the group yields before the occupancy when the terminal is too narrow for both. Plan mode adds a `plan` marker beside the Agent state, toggled by `Shift+Tab` through `ctx.planMode`. The key hints are the placeholder of the empty composer rather than a footer line: the composer is wrapped so its content line shows them until the first typed character, because the editor component renders no placeholder of its own. Occupancy and capacity come from the `contextPressure` projection of the mounted `ctx.tokenMeter`, the totals from its `tokenUsage` projection, and the throughput from the `sessionStats` projection this bundle inserts; the `(auto)` marker comes from `ctx.compaction.autoCompactionEnabled`; the model's provider qualifies the label only when the deployment registers several. [`src/views.ts`](src/views.ts) turns rows into terminal lines with [`@earendil-works/pi-tui`](https://www.npmjs.com/package/@earendil-works/pi-tui) components, truncating every line to the viewport width because the renderer treats an over-wide line as a component defect, and flattening a Tool heading to one line because one row owns exactly one terminal row: a multi-line argument would otherwise print its own line breaks and spill the row into the pinned footer. A picker or prompt renders as ordinary output rather than a dialog — a plain title, a blank row, and the body — anchored directly above the composer in the alternate-screen layout, with every row padded to the viewport width so the transcript cannot show through beside it. The alternate-screen renderer owns scrolling: the transcript is its primary scroll view, so PageUp/PageDown and the wheel move the transcript while the status bar and composer stay pinned; stopping the renderer writes the whole transcript back to the normal screen, so the output stays selectable after exit. `stop()` then flushes the session and writes the resume command to stderr, after the restore because the surface no longer owns the screen, and only where a persistence backend is mounted. A Tool's declared Host presentation decides its row: the call and result views resolved through `ctx.tools` while the fold runs render as a `card: 'diff'` unified diff with the Tool's own heading and a `+added -removed` count, a `card: 'terminal'` command with its description, working directory, output, and exit-status pill, a `card: 'read'` numbered line window, a `card: 'search'` grouped match or path list with its cap signal, a `card: 'web'` cited-source or fetch summary, and a `card: 'generic'` title with its salient input. A card body folds after a bounded number of lines; a settled result view replaces the pending one, an omitted result view keeps the call-time card, and a failed mutation falls back to the ordinary name-and-summary row with its error text. A Tool row's ordinary result body renders in the palette's tool-result grey rather than the assistant body's terminal foreground. The palette follows the terminal background: `colorScheme` pins dark or light, and `auto` reads the terminal's `COLORFGBG` background signal, defaulting to dark. Switching sessions releases the transcript view’s cached lines and Markdown components. Provider reasoning stays visible after streaming ends and is restored from the session log when resuming.
+
+### Interaction seams
+
+The app requires the approval service to record remembered tool grants and answers the two seams the Agent pauses on. `ctx.on('approval/request', …)` offers Allow once / Always allow / Reject for this app's own Agent and every live subagent descendant, naming the child's descriptor label in the heading; every other Agent's request is delegated, so a composition that also mounts another surface keeps its own answerers authoritative. Always allow records a per-tool grant on the app's own root Agent, so the choice covers the session and every live subagent; later asks for that tool settle without a prompt, their audit rows read `allowed always`, and a resumed session keeps the grant. Prompts are serialized, so concurrent requests queue in arrival order, and a skipped or cancelled prompt resolves `cancelled`, which the approval service already treats as fail-closed. Every ask and decision also folds into a durable `approval · <tool> — <outcome>` transcript row: the app's own decisions appear in its transcript, and a child's appear in the child's watch viewer. `ctx.on('user-questions/request', …)` renders the question's options as a picker — a checkable list when the question sets `multiSelect`, where Space toggles the highlighted option and Enter submits the checked labels in list order, doing nothing while none is checked — or a free-text input when the question declares none. Both option kinds gain a final `Other…` row that opens that free-text input instead: a single selection is replaced by the typed answer and a multi-selection keeps its checked labels alongside it. Escape skips the question with an empty selection so the batch advances, and Ctrl+C fails the asking Tool with `ASK_ABORTED`; a plan review answered with Keep planning — or left unanswered any other way — fails it with `ASK_CANCELLED`, which plan mode reads as the user taking the turn back, while its `Other…` feedback reaches the model instead. A question's `detail` renders as markdown above that control, in a viewport sized to the rows the control leaves; a prompt whose question carries a detail takes every row above the pinned composer and footer, while one without a detail keeps the picker's own height cap so a short list never fills a tall terminal. While the detail overflows, Up/Down, PageUp/PageDown, and the wheel scroll it and Left/Right move the picker, so a plan review shows the plan the model submitted rather than only its approval options. The picker itself installs no mouse handler, so a stray click cannot move its highlight or confirm an option, and the wheel pages the transcript behind the prompt; only a detail that overflows takes the wheel for its own viewport. One prompt owns the keyboard at a time. A question's heading wraps across at most three rows — a dim label carrying the batch position and header above the question — with a timed window's countdown pinned to its first row.
+
+`ask_user_question` runs in its timed form. The app claims the call's foreground window from the service and counts the seconds left in the heading, and a window the user does not answer inside — including one they cancel — settles the Tool as pending rather than failing it, so the question stays answerable. `/questions` lists every call this session still owes an answer, presents each question through the same prompt a live one uses, and hands the finished batch to the service, which steers it into the Agent as a user message the transcript shows as the user's reply. The transcript row of a settled call lists each question with the labels the user chose, or a skip marker, and a still-waiting timed call says so instead of showing its result JSON.
+
+### Clipboard images
+
+Ctrl+V reads the system clipboard through the platform's own reader ([`src/clipboard.ts`](src/clipboard.ts)): `osascript`'s JavaScript automation runtime reading `NSPasteboard` directly on macOS, PowerShell on Windows and WSL, `wl-paste` on Wayland, and `xclip` on X11. A reader stages bytes in a temporary file that the read deletes, and its declared media type is only a claim — the attachment service verifies it against the decoded bytes. The footer reports `pasting image…` from the key press until the bytes arrive, because a platform reader runs as a child process and a large clipboard image can take most of a second to stage. The bytes stay in memory under the marker the composer shows. A submission citing a marker resolves the exact routed model's declared input modalities, admits the batch through `ctx.attachments.admitPromptContent(…)`, and hands the Agent one user message carrying the prompt text followed by the admitted image blocks. A refusal — no attachment store, a model that excludes image input, or a failed admission — restores the draft rather than sending a partial prompt.
+
+### Patch surface over base
+
+The patch rides over `dsh-base` and adds no Host or browser row. It restates the coding persona the other surfaces set, inserts the startup provider and the app, and leaves the base's model-facing rows in the host plane: this surface is single-session, so its Agent composes them process-wide instead of per session. The startup provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), parses `--resume`, `--provider`, `--model`, and `--watch`, and provides `tuiStartup`; the app row injects that service, so `--help` and a rejected invocation mount no terminal UI at all. `--watch` is mutually exclusive with the session flags and boots [`src/watch/viewer.ts`](src/watch/viewer.ts) instead of the interactive app. The first local subagent starts the in-process Node HTTP listener owned by [`src/watch/server.ts`](src/watch/server.ts); it serves only that TUI's local subagent tree and exits with the TUI. The patch also mounts `tool-ask-user` in its `mode: timed` form, because the base layer provides the question service but no question tool. It sets `tool-fs.applyPatch: true`, adding `apply_patch` beside `edit`; `dsh-base` keeps the tool switched off for the other surfaces. The patch also sets `session-log-deepseek` to `enabled: false`, so this fork keeps Session logs on the machine instead of contributing the upstream `dsh_session_log` suffix to official DeepSeek requests; a deployment that wants that suffix re-enables the row through a `--patch` overlay or the profile's own `cordis.patch.yml`. The patch sets `subagent.delegatedApproval: inherit`, so a local child inherits the parent's effective approval policy and the app's descendant answerer can decide its asks; deployments that need unattended delegation restore the package default `never`.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | The `tui-app` plugin: launcher facts, boot, and failure exit |
+| [`src/startup.ts`](src/startup.ts) | The `tui-startup` provider: flag family and `--help` |
+| [`src/app.ts`](src/app.ts) | Surface construction, event wiring, input routing, teardown |
+| [`src/diagnostics.ts`](src/diagnostics.ts) | Console capture while the surface owns the terminal |
+| [`src/session.ts`](src/session.ts) | Agent create/resume, stored-history read, prompt submission, route switching |
+| [`src/transcript.ts`](src/transcript.ts) | The event fold into renderable rows |
+| [`src/diff.ts`](src/diff.ts) | The pure file-diff row model |
+| [`src/tool-view.ts`](src/tool-view.ts) | The Host tool-presentation bridge |
+| [`src/images.ts`](src/images.ts) | Composer image markers and the submission fold |
+| [`src/clipboard.ts`](src/clipboard.ts) | Platform clipboard image readers and their staging files |
+| [`src/views.ts`](src/views.ts) | Transcript, status bar, and modal panel components |
+| [`src/commands.ts`](src/commands.ts) | Slash-command catalog, dispatch, and model catalog |
+| [`src/interactions.ts`](src/interactions.ts) | Approval and user-question answerers |
+| [`src/ansi.ts`](src/ansi.ts) | Semantic styles and the component themes |
+| [`src/watch/protocol.ts`](src/watch/protocol.ts) | NDJSON wire vocabulary and record validation |
+| [`src/watch/record.ts`](src/watch/record.ts) | Private runtime record publication and cleanup |
+| [`src/watch/server.ts`](src/watch/server.ts) | Loopback stream service, child state, and bounded client queues |
+| [`src/watch/client.ts`](src/watch/client.ts) | Authenticated stream reader and wire validation |
+| [`src/watch/history.ts`](src/watch/history.ts) | Read-handle history access for the viewer |
+| [`src/watch/viewer.ts`](src/watch/viewer.ts) | Read-only watch surface and its footer |
+| [`cordis.patch.yml`](cordis.patch.yml) | The terminal patch over `dsh-base` |
+| — | No runtime invariant companion is published; the app registers no registry, and its watch records are disposable runtime data rather than Session state. |
+| [`tests/tui-app.spec.ts`](tests/tui-app.spec.ts) | Composer routing, clipboard paste, rendering, modal answers, and exit |
+| [`tests/diagnostics.spec.ts`](tests/diagnostics.spec.ts) | Console formatting, plain-text sanitization, and method restoration |
+| [`tests/transcript.spec.ts`](tests/transcript.spec.ts) | The event fold, the footer, the placeholder composer, and line-width bounds |
+| [`tests/clipboard.spec.ts`](tests/clipboard.spec.ts) | Every platform reader path and the staging-file adapters |
+| [`tests/images.spec.ts`](tests/images.spec.ts) | Composer marker parsing |
+| [`tests/startup.spec.ts`](tests/startup.spec.ts) | Command-line parsing over a real Loader tree |
+| [`tests/watch.spec.ts`](tests/watch.spec.ts) | Record publication, authenticated streaming, continuity checks, history fallback, and the viewer |
+
+### Invariant ownership
+
+No invariant companion is published: the app contributes no registry, its watch records are disposable runtime data with an owner-only access token, and its observable contract is the terminal surface, which the surface tests drive through a substituted Terminal.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages to go deeper into the shared core, the sibling surfaces, or the terminal library.
+
+- [Bundle package map](../README.md) — the surfaces built on the same core.
+- [dsh-base](../base/README.md) — the shared core this surface runs on.
+- [dsh-headless](../headless/README.md) — the one-shot sibling for scripts and CI.
+- [dsh-web-app](../web-app/README.md) — the browser sibling for multi-turn work.
+- [dsh-cmdline](../../boot/cmdline/README.md) — how the launcher hands the command line to the app.
+- [Interactive delegated approvals](../../../.agents/notes/implemented/architecture/2026-10-22-interactive-delegated-approvals.md) — why this surface answers its live descendants and how the policy is seeded.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tui-app) — every accepted config field and its source declaration.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Interactive coding session
+
+#### What the model sees
+
+The composition enables `apply_patch`, so every request carries that tool's schema and its system-prompt guidance beside the base file tools. The app submits the typed prompt as an ordinary user message and renders the model's own output back; `/help`, `/quit`, `/new`, `/sessions`, `/resume`, and `/model` never reach the model. A model switch appends the shared model-selection notice, exactly as it does on the other surfaces. Shift+Tab enters or leaves plan mode through the same service `/plan` drives, so the model sees the plan-policy section and the user-switch notice a typed command produces. A clipboard paste adds the admitted image to that same message as a durable image reference, exactly as an upload from another surface does; the composer's `[Image N]` markers are composer text and never reach the model.
+
+#### Token effect
+
+Prompts and responses carry their ordinary token cost. The `apply_patch` schema and guidance are input tokens on every request. Nothing the terminal renders — the footer, the Tool row folding, or the scroll window — adds a request or a token; the occupancy, throughput, and token-total figures are read from local measurement projections, not from an extra provider call. Toggling plan mode adds no request of its own and changes only the next request's plan-policy section. An attached image is counted at the routed model's declared image pricing when it declares one, so the footer reflects the request the model will actually receive.
+
+#### KV Cache effect
+
+The profile's extra `apply_patch` schema and guidance are part of the stable request prefix and do not change between turns; the app otherwise adds nothing to the prefix and only routes the typed prompt through the composed tree.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define what the terminal surface does not do. They are current constraints of this bundle, not a backlog of the browser surface.
+
+- **One Agent per invocation** — the app owns a single session; switching to another Agent means `/new` or `/resume`, which opens the replacement before closing the current one so a failed open leaves the live session in place.
+- **Always allow is app-wide and session-scoped** — choosing it on any prompt, including a child's, records the grant on the root Agent and covers every live subagent for the rest of the session; the surface has no revoke control.
+- **Subagent approvals need a live lineage** — the app answers only its own Agent and live descendants; a child whose parent chain is no longer live, or whose profile pins `delegatedApproval: never`, resolves without a terminal prompt.
+- **Keep planning waits for a message** — the terminal review has no free-text feedback field, so choosing Keep planning closes the review and hands the turn back, keeping plan mode active; the adjustment is the user's next prompt rather than an answer carried on the review.
+- **A prompt's height is fixed when it opens** — the panel sizes itself from the terminal once, so resizing the terminal during a review does not resize it; close and reopen the prompt to pick up the new height.
+- **Images come only from the clipboard** — the composer attaches PNG, JPEG, WebP, and GIF bytes read from the system clipboard, through `osascript` reading `NSPasteboard` on macOS, PowerShell on Windows and WSL, `wl-paste` on Wayland, or `xclip` on X11. A host with none of those readers reports the paste as an empty clipboard, and no file picker, drag-and-drop, or non-image attachment exists.
+- **A late reply is a follow-up** — the timed Tool already returned its pending result, so `/questions` steers the answer into the Agent as a new user message; the recorded call is not resumed.
+- **Tool output is folded** — a Tool result shows its first lines plus a count of the remainder; the complete output stays in the session log, not on screen.
+- **Cards render as text** — every Host card draws as terminal rows: a read window carries no syntax highlighting, a generic card's `kind` icon and `locations` follow-along are not drawn, and a terminal card replays the captured output rather than a live session.
+- **Occupancy is an estimate** — the footer's percentage anchors on the last provider-reported prompt size and heuristically reprices what the surface gained or lost since; it is a reference for the user, not a billing or admission input.
+- **Launcher-owned exit** — like every surface, the app starts only through the `dsh` profile, because only the launcher provides the bounded exit request.
+- **No recorded-session snapshot** — the keyless snapshot harness drives shipped profiles over stdio, while this surface owns a terminal; its acceptance is the package tests plus a pseudo-terminal run rather than a snapshot fixture, so a regression in terminal layout needs the surface tests to be extended rather than a re-recorded snapshot.
+- **Watching is local and first-version** — only local subagents started by a TUI, including nested ones, are viewable. Web, headless, SDK, and remote-machine sessions are out of scope, the viewer never reconnects automatically, and the writer side does not relay raw tool stdout. Tokens generated before the original process crashes but not committed to the Session log are not recoverable; the viewer keeps only what it already displayed and reports the interruption.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>