@itookit/dsht 0.3.7 → 0.3.8

package/README.i18n.yaml

@@ -1,3 +1,3 @@
 # Git blob hashes of the reviewed bilingual pair.
-README.md: 92c2be7222eebf3a4377d320d6107415e483a338
-README.zh.md: 810b6f5f4cc3a417aa99d0c61aa61700d6df3a37
+README.md: ce72e2f65a0834f3c58925ab907a5ad39653eca1
+README.zh.md: 432aea7bb61f908845055aa06a1779156ad33258

package/README.md

@@ -166,7 +166,7 @@ npm start
 
 Both paths read the same `DSH_URL` and `DSH_TOKEN` variables.
 
-Select a workspace with ↑/↓ and Enter, then select a session or **New session**. **All sessions** also exposes sessions outside registered workspaces. **Add workspace (this directory)** registers the directory `dsht` itself runs in, and appears only while the host does not already have it; **Add workspace (host directory)** takes an existing absolute directory on the host, which may differ from your local filesystem, and Esc leaves that prompt for the picker again. Creating a session requires a selected workspace.
+Select a workspace with ↑/↓ and Enter, then select a session or **New session**. **All sessions** also exposes sessions outside registered workspaces. **Add workspace (this directory)** registers the directory `dsht` itself runs in, and appears only while the host does not already have it; **Add workspace (host directory)** takes an existing absolute directory on the host, which may differ from your local filesystem, and Esc leaves that prompt for the picker again. Starting inside a registered workspace directory selects that workspace instead of showing the picker, with `←` in the session list switching to another; a session id passed on the command line still opens directly. Creating a session requires a selected workspace.
 
 On first login, authentication exchanges the token at `GET /` and saves the cookie per HTTP origin. Later starts, including list commands, reuse that cookie without a token. The store uses `$XDG_STATE_HOME/dsht/auth`, or `~/.local/state/dsht/auth` when unset; `--auth-dir` or `DSHT_AUTH_DIR` overrides it. POSIX directories use 0700 and cookie files use 0600; Windows uses the account directory's inherited access controls. Launch tokens are never saved.
 
@@ -298,6 +298,7 @@ In `/ws` and `/resume` pickers, every row reports one of three user-visible stat
 `/search` matches literal text case-insensitively in conversation messages, including older pages; tool-only rows are excluded. Search scans up to 80 messages per request, discards each temporary page, and retains at most 200 short matches, including folded reasoning. A truncated result asks you to refine the query. Opening a match loads a separate page around its sequence; `/latest` releases that window. Esc or Ctrl+C cancels the search. A rare or absent term still requires scanning the full history over HTTP; there is no server-side full-text index for this command. `/history` lists your own prompts from the loaded pages. Record sequences are the numbers shown by these pickers. `/ssearch` and `/wsearch` call `session/search`, which searches current user/assistant message content and returns at most 20 sessions, snippets, and a truncation flag; it exposes neither a result cursor nor matching record sequences. Workspace filtering happens after that global limit, so a truncated workspace result can omit matches. The UI warns when results are incomplete; refine the query. Selecting a session loads its history and offers matching messages for the jump. These operations use HTTP and never scan the host configuration directory.
 
 ↑/↓ or Ctrl+P/N recalls previously submitted prompts and slash commands without sending them; Enter submits the recalled text. A reading panel that fits the screen leaves the arrows with this history, a panel that has to scroll takes them for itself, and Ctrl+P/N reach the history from any panel. Moving past the newest entry restores the unsent draft. Editing recalled text starts a new draft, and switching sessions clears an unsent one. Recall keeps the selected session's user prompts — up to 2,000 entries and approximately 512 KiB of text — and never writes a separate history file; switching sessions releases them. It folds those prompts from the session records as they arrive, so it covers prompts from before this client connected rather than only the window that happened to load. Opening a session also walks the earlier history in the background, keeping only prompts rather than loading those pages into the conversation, so the whole session's prompt list is available from the start. Reaching its oldest retained prompt first refills from the already-loaded conversation at no request cost, and only then fetches the page before the window, inside one bounded loop that skips tool-only pages so the key cannot stall; the fetched page also stays in the conversation above the composer. Eviction therefore bounds memory without deciding reachability: an evicted prompt is either still loaded or still on the host. Consecutive duplicates are merged, oversized entries are skipped, and question or approval answers are excluded. Question options and completion menus keep arrow navigation; workspace/session lists use arrows when the composer is empty, with Ctrl+P/N available for recall.
+`!command` runs that command on the machine this client is on — not on the host the agent works in — and prints the command and its output inline in the conversation, where it stays in place and scrolls away with the history; nothing is sent to the model and nothing is written to disk. Output is capped at 200 lines and 64 KiB per command, only the last 20 commands are kept, and the number of dropped lines is stated in the block. One command runs at a time; Esc, or Ctrl+C on an empty prompt, stops it by killing its whole process group, so pipelines and background children die with it; a command that needs a terminal of its own, such as `vim`, cannot work. `--no-shell` or `DSHT_NO_SHELL=1` disables the prefix.
 
 Within each User group, only the first assistant prose or reasoning message shows an Assistant heading. Later messages and live output reuse that heading across tool results and Context messages. A newly loaded history window starts its own visible group; message sequences, tool status, search, and reasoning expansion remain independent.
 
@@ -426,7 +427,7 @@ This repository publishes one public package, `@itookit/dsht`, from the `mushuan
 
 | Field | Value |
 | --- | --- |
-| Name and version | `@itookit/dsht` `0.3.7` |
+| Name and version | `@itookit/dsht` `0.3.8` |
 | Executable | `dsht`, or `npx @itookit/dsht` without installing |
 | Library entries | `@itookit/dsht` and `@itookit/dsht/auth` |
 | Author | lizlok@gmail.com |

package/README.zh.md

@@ -166,7 +166,7 @@ npm start
 
 两种方式读取相同的 `DSH_URL` 和 `DSH_TOKEN` 变量。
 
-使用 ↑/↓ 和 Enter 选择工作区，然后选择已有会话或 **New session**。**All sessions** 同时显示未归属注册工作区的会话。**Add workspace (this directory)** 直接注册 `dsht` 自身所在的目录，只在服务端尚未注册它时出现；**Add workspace (host directory)** 接收服务端已有目录的绝对路径，该路径可能与本机文件系统不同，按 Esc 可以退回选择器。新建会话前必须选择工作区。
+使用 ↑/↓ 和 Enter 选择工作区，然后选择已有会话或 **New session**。**All sessions** 同时显示未归属注册工作区的会话。**Add workspace (this directory)** 直接注册 `dsht` 自身所在的目录，只在服务端尚未注册它时出现；**Add workspace (host directory)** 接收服务端已有目录的绝对路径，该路径可能与本机文件系统不同，按 Esc 可以退回选择器。在已注册的工作区目录里启动时，直接选中该工作区而不再显示选择器（会话列表里的 `←` 仍可切到别的工作区）；命令行给出会话 ID 时依旧直接打开。新建会话前必须选择工作区。
 
 首次登录通过 `GET /` 兑换 token，并按 HTTP origin 保存 cookie。后续启动和列表命令自动复用 cookie，无需再次提供 token。默认目录为 `$XDG_STATE_HOME/dsht/auth`，未设置时使用 `~/.local/state/dsht/auth`；可通过 `--auth-dir` 或 `DSHT_AUTH_DIR` 覆盖。POSIX 下目录权限为 0700、cookie 文件为 0600；Windows 使用账户目录继承的访问控制。启动 token 永不保存。
 
@@ -298,6 +298,7 @@ Enter 提交消息：代理处于 Working 时自动作为下一个 step 的转
 `/search` 对对话消息进行不区分大小写的字面文本匹配，包含旧页，排除纯工具行。搜索每次请求最多 80 条消息，扫描后释放临时页，只保留最多 200 条简短命中摘要，包含折叠的思考；结果截断时提示缩小查询范围。选择命中项只加载其序号附近的独立页面，`/latest` 释放该窗口。Esc 或 Ctrl+C 可取消搜索。稀有词或无匹配查询仍需通过 HTTP 扫描全部历史，此命令尚无服务端全文索引。`/history` 只列出已加载页面中自己的提示词，选择器显示的数字就是记录序号。`/ssearch` 与 `/wsearch` 调用 `session/search`，服务端搜索当前用户／助手消息内容，最多返回 20 个会话、摘要和截断标记，没有结果分页游标或命中记录序号。工作区筛选在全局数量限制之后进行，因此截断时可能漏掉工作区内的匹配会话；界面会提示结果不完整，可缩小查询范围。选择会话后加载其历史，再选择匹配消息跳转。所有操作均通过 HTTP 完成，不扫描服务端配置目录。
 
 ↑/↓ 或 Ctrl+P/N 回填之前提交的提示词和 slash 命令，按 Enter 才提交。一屏放得下的阅读面板会把方向键留给该历史，需要滚动的面板才接管方向键，而 Ctrl+P/N 在任何面板打开时都能回填。向下越过最新记录时恢复未发送草稿；编辑回填内容后开始新的草稿，切换会话会清空未发送的草稿。回填按当前会话保留其 user prompt，最多 2,000 条、约 512 KiB 文本，且不写入独立历史文件；切换会话即释放。它在记录到达时增量折叠这些提示词，因此覆盖本客户端连接之前的提示词，而不只是碰巧加载的那个窗口。打开会话后它还会在后台把更早的历史翻一遍，只提取提示词、不把这些页读进上方对话，因此从会话开始就持有整个会话的提示词列表。走到索引里最旧一条时，先用已加载的对话补回被预算淘汰的提示词，这一步不发请求；只有窗口也用尽才取回窗口之前的一页，并在同一次有界循环里跳过整页没有 User 消息的页，因此按键不会被工具页卡住；取回的那页也会留在输入框上方的对话里。于是淘汰只约束内存、不决定可达性：被淘汰的提示词要么仍在窗口内，要么仍在宿主上。连续重复输入合并，超大输入跳过，提问和审批回答不记入历史。提问选项与补全菜单优先使用箭头；工作区／会话列表在输入框为空时使用箭头选择，可用 Ctrl+P/N 调出输入历史。
+`!命令` 在这台运行客户端的机器上执行——不是 agent 所在的宿主——并把命令行与输出内联打印在对话里、留在它发生的位置随历史一起滚走；不会发给模型，也不写入磁盘。每条命令的输出上限为 200 行与 64 KiB，只保留最近 20 条命令，被丢弃的行数会在块内注明。同一时刻只运行一条命令；Esc（或输入框为空时 Ctrl+C）会终止其整个进程组来停止它，因此管道与后台子进程一起结束；需要独占终端的命令（如 `vim`）无法工作。`--no-shell` 或 `DSHT_NO_SHELL=1` 关闭该前缀。
 
 每条 User 消息之后，只在第一段助手正文或思考前显示 Assistant 标题；后续消息及流式输出沿用分组，工具结果和 Context 消息不重置分组。当前加载的历史窗口从自身起点建立可见分组，消息序号、工具状态、搜索和思考展开仍各自保留。
 
@@ -426,7 +427,7 @@ Slash 命令在选择器和对话输入框中均可使用。输入 `/` 会显示
 
 | 字段 | 值 |
 | --- | --- |
-| 名称与版本 | `@itookit/dsht` `0.3.7` |
+| 名称与版本 | `@itookit/dsht` `0.3.8` |
 | 可执行命令 | `dsht`，不安装时用 `npx @itookit/dsht` |
 | 库入口 | `@itookit/dsht` 和 `@itookit/dsht/auth` |
 | 作者 | lizlok\@gmail.com |

package/dist/cli/dsht.js

@@ -26,6 +26,7 @@ With no command, choose a workspace and session interactively.
   --history-mb <n>      Soft history payload budget in MiB (default 16)
   --memory-log <path>   Append runtime memory samples; a failing log stops itself
   --no-memory-log       Disable the runtime memory log (default: enabled)
+  --no-shell            Disable ! local commands (DSHT_NO_SHELL=1)
   --json               Print machine-readable list output
   --help               Show this help
 
@@ -33,6 +34,7 @@ The default host is http://127.0.0.1:3080.
 First login: export DSH_TOKEN, or export DSH_URL as the URL printed by dsh web.
 Cookies are saved per server origin and reused on later starts. Tokens are never saved.
 /cost shows the session and today CNY estimates.
+!command runs on this machine, not on the host, and prints its output in the transcript.
 DSHT_CONFIG_DIR overrides the prices.json directory; DSHT_STATE_DIR overrides usage storage.
 The memory log defaults to <state>/memory.log; DSHT_MEMORY_LOG sets another path or 'off'.
 prices.json overrides the shipped rates and is seeded on first use; every scan re-decides the
@@ -47,7 +49,7 @@ async function main() {
             url: { type: 'string', default: process.env.DSH_URL ?? 'http://127.0.0.1:3080' },
             'history-records': { type: 'string' }, 'history-mb': { type: 'string' },
             workspace: { type: 'string' }, session: { type: 'string' }, 'auth-dir': { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean' },
-            'memory-log': { type: 'string' }, 'no-memory-log': { type: 'boolean' },
+            'memory-log': { type: 'string' }, 'no-memory-log': { type: 'boolean' }, 'no-shell': { type: 'boolean' },
         } });
     if (values.help) {
         process.stdout.write(HELP);
@@ -93,7 +95,8 @@ async function main() {
     await costs.load();
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         throw new Error('Interactive mode requires a terminal. Use list workspaces or list sessions for scripts.');
-    const controller = new Controller(url, token, values.session, undefined, client => login(client, token, store), costs, limits, memoryLogPath(stateRoot, values['memory-log'], values['no-memory-log']));
+    const shellEnabled = !values['no-shell'] && process.env.DSHT_NO_SHELL !== '1';
+    const controller = new Controller(url, token, values.session, undefined, client => login(client, token, store), costs, limits, memoryLogPath(stateRoot, values['memory-log'], values['no-memory-log']), undefined, shellEnabled);
     const app = mount(controller);
     const terminate = () => app.unmount();
     process.once('SIGTERM', terminate);

package/dist/controller/controller.d.ts

@@ -11,6 +11,7 @@ import { CostController } from '../cost/controller.ts';
 import { ConnectionController, type ConnectionListener } from './connection.ts';
 import { MemoryLog } from './memory-log.ts';
 import { type ControllerStore, type State } from '../state.ts';
+import { ShellController } from '../shell/index.ts';
 import type { HistorySearch, RemovalTarget } from '../session/types.ts';
 import type { ComposerState, InteractionState, ModelState, OptionState, PanelState, ReferenceState, ViewState } from '../session/info.ts';
 import type { Reasoning } from '../session/history.ts';
@@ -38,11 +39,15 @@ export declare class Controller implements ControllerStore, ConnectionListener {
     readonly cost: CostController | undefined;
     /** Bounded runtime memory samples; present only when a log path was supplied. */
     readonly memoryLog: MemoryLog | undefined;
+    /** Local `!` commands, run on this machine and shown inline in the transcript. */
+    readonly shell: ShellController;
     private readonly observers;
     private selector;
     constructor(base: string, token: string | undefined, initialSession?: string | undefined, makeClient?: () => Client, authenticate?: (client: Client) => Promise<void>, costs?: CostLedger | undefined, historyLimits?: HistoryLimits, memoryLogPath?: string | undefined, 
     /** Directory this client runs in, offered as a workspace when the host has not registered it. */
-    localDirectory?: string);
+    localDirectory?: string, 
+    /** Whether `!` may run local commands; the CLI disables it with `--no-shell`. */
+    shellEnabled?: boolean);
     /** React-compatible state subscription. */
     subscribe: (listener: () => void) => (() => void);
     /** Snapshot identity changes only when the controller publishes. */

package/dist/controller/controller.js

@@ -13,6 +13,20 @@ import { ConnectionController } from "./connection.js";
 import { MemoryLog } from "./memory-log.js";
 import { clearReactMeasures, measureCount } from "./perf-measures.js";
 import { initialState } from "../state.js";
+import { ShellController } from "../shell/index.js";
+/** Environment for a local `!` command: this client's variables without its credentials.
+ *
+ * `DSH_URL` is removed as well as the token, because the URL form the README documents can carry a
+ * token in its query string. Commands therefore run with the operator's environment, not this
+ * client's session.
+ * @returns A copy of the environment safe to hand to a child process.
+ */
+function shellEnv() {
+    const env = { ...process.env };
+    delete env.DSH_TOKEN;
+    delete env.DSH_URL;
+    return env;
+}
 /** Application facade over the domain controllers; the UI owns only this object.
  *
  * State lives here, connection generations live in `connection`, the selected session and its
@@ -36,11 +50,15 @@ export class Controller {
     cost;
     /** Bounded runtime memory samples; present only when a log path was supplied. */
     memoryLog;
+    /** Local `!` commands, run on this machine and shown inline in the transcript. */
+    shell;
     observers = new Set();
     selector = 0;
     constructor(base, token, initialSession, makeClient = () => new Client(base), authenticate = client => client.authenticate(token ?? ''), costs, historyLimits = DEFAULT_HISTORY_LIMITS, memoryLogPath, 
     /** Directory this client runs in, offered as a workspace when the host has not registered it. */
-    localDirectory = process.cwd()) {
+    localDirectory = process.cwd(), 
+    /** Whether `!` may run local commands; the CLI disables it with `--no-shell`. */
+    shellEnabled = true) {
         this.base = base;
         this.initialSession = initialSession;
         this.costs = costs;
@@ -50,6 +68,12 @@ export class Controller {
         const options = { base, token, initialSession, makeClient, authenticate };
         this.connection = new ConnectionController(this, options, this);
         this.session = new SessionController(this, this.connection, this.connection, historyLimits);
+        this.shell = new ShellController({
+            publish: () => this.update({}),
+            cwd: () => this.localDirectory,
+            env: () => shellEnv(),
+            anchor: () => this.state.session.record.readThrough,
+        }, shellEnabled);
         this.catalog = new CatalogController(this, this.connection);
         if (costs)
             this.cost = new CostController(costs, {
@@ -95,6 +119,7 @@ export class Controller {
     start() { this.connection.start(); this.memoryLog?.start(); }
     /** Cancel retries and HTTP, close the socket, and release session and catalog work. */
     async stop() {
+        await this.shell.stop();
         await this.connection.stop();
         await this.session.settle();
         await this.catalog.settle();
@@ -196,6 +221,11 @@ export class Controller {
         this.update({ online: true, status: 'Connected', error: '', pending: [] });
         const screen = this.state.screen;
         await this.session.showPicker(screen === 'sessions' ? 'sessions' : 'workspaces');
+        // Starting inside a registered workspace's directory already answers the first question, so the
+        // reader lands on that workspace's sessions instead of a list they would pick from by hand.
+        if (screen !== 'sessions' && !this.initialSession && this.session.adoptLocalWorkspace(this.localDirectory) !== undefined) {
+            this.update({ status: 'Workspace from this directory · ← to switch' });
+        }
         const sessionId = this.state.sessionId ?? this.initialSession;
         if (sessionId && (screen === 'chat' || this.initialSession && !this.state.sessionId))
             await this.session.selectSession(sessionId);

package/dist/session/controller.d.ts

@@ -121,6 +121,15 @@ export declare class SessionController {
     switchSession(query?: string): Promise<void>;
     /** Prompt for a host path without starting a local agent. */
     enterPath(): void;
+    /** Adopt the workspace whose registered path contains the directory this client runs in.
+     *
+     * Longest path wins, so a workspace nested in another is preferred, and the comparison is on whole
+     * path segments so `/srv/app-old` cannot match `/srv/app`. A remote host's paths usually differ
+     * from the client's, in which case nothing matches and the picker stays exactly as before.
+     * @param directory - Directory this client was started in.
+     * @returns The adopted workspace's id, or undefined when none matches.
+     */
+    adoptLocalWorkspace(directory: string): string | undefined;
     /** Register a host directory and move to its session picker.
      * @param path - Absolute directory path on the host.
      */

package/dist/session/controller.js

@@ -297,6 +297,32 @@ export class SessionController {
     }
     /** Prompt for a host path without starting a local agent. */
     enterPath() { this.store.update({ screen: 'path' }); }
+    /** Adopt the workspace whose registered path contains the directory this client runs in.
+     *
+     * Longest path wins, so a workspace nested in another is preferred, and the comparison is on whole
+     * path segments so `/srv/app-old` cannot match `/srv/app`. A remote host's paths usually differ
+     * from the client's, in which case nothing matches and the picker stays exactly as before.
+     * @param directory - Directory this client was started in.
+     * @returns The adopted workspace's id, or undefined when none matches.
+     */
+    adoptLocalWorkspace(directory) {
+        const slashed = (value) => value.replace(/\\/g, '/').replace(/\/+$/, '');
+        const target = slashed(directory);
+        if (target === '')
+            return undefined;
+        let best;
+        for (const workspace of this.store.state.workspaces) {
+            const path = slashed(string(workspace.path));
+            if (path === '' || (target !== path && !target.startsWith(`${path}/`)))
+                continue;
+            if (best === undefined || path.length > best.length)
+                best = { id: string(workspace.workspaceId), length: path.length };
+        }
+        if (best === undefined)
+            return undefined;
+        this.pickWorkspace(best.id);
+        return best.id;
+    }
     /** Register a host directory and move to its session picker.
      * @param path - Absolute directory path on the host.
      */

package/dist/session/history.d.ts

@@ -3,7 +3,7 @@ import { type MarkdownSpan } from './markdown.ts';
 /** Default fold mode; individual sequence overrides are view state, never stored content. */
 export type Reasoning = 'row' | 'full';
 /** Color semantics are independent of the selected terminal palette. */
-export type RowKind = MessagePart['kind'] | 'user' | 'assistant' | 'context' | 'muted';
+export type RowKind = MessagePart['kind'] | 'user' | 'assistant' | 'context' | 'muted' | 'shell';
 /** One visible terminal row; no remote ANSI is allowed into its text. */
 export interface HistoryRow {
     text: string;
@@ -11,7 +11,27 @@ export interface HistoryRow {
     bold?: boolean;
     seq?: number;
     spans?: MarkdownSpan[];
+    /** Draw the row on the theme's local-command bar, used by `!` commands. */
+    highlight?: boolean;
 }
+/** Wrap text into rows with the per-kind trimming rule.
+ * @param text - Text to wrap.
+ * @param width - Available terminal columns.
+ * @param kind - Part kind, which decides whether wrapped lines are trimmed.
+ * @param seq - Durable sequence, for committed parts.
+ * @returns The wrapped rows.
+ */
+/** Wrap plain local text into terminal rows, preserving its own whitespace.
+ *
+ * Command output is aligned by spaces and indented by stack traces, so this never collapses runs of
+ * whitespace the way tool summaries do; only the terminal width decides where a row breaks.
+ * @param text - Raw text, possibly containing newlines.
+ * @param width - Available terminal columns.
+ * @param kind - Row kind used for coloring.
+ * @param highlight - Whether the rows are a local command line drawn on the command bar.
+ * @returns One row per wrapped terminal line; empty text yields one empty row.
+ */
+export declare function plainRows(text: string, width: number, kind: RowKind, highlight?: boolean): HistoryRow[];
 /** Drop all terminal rows and layout metadata for an evicted or inactive transcript.
  * @param transcript - Transcript whose previously returned layout is no longer used.
  */

package/dist/session/history.js

@@ -140,6 +140,21 @@ const liveRows = new WeakMap();
  * @param seq - Durable sequence, for committed parts.
  * @returns The wrapped rows.
  */
+/** Wrap plain local text into terminal rows, preserving its own whitespace.
+ *
+ * Command output is aligned by spaces and indented by stack traces, so this never collapses runs of
+ * whitespace the way tool summaries do; only the terminal width decides where a row breaks.
+ * @param text - Raw text, possibly containing newlines.
+ * @param width - Available terminal columns.
+ * @param kind - Row kind used for coloring.
+ * @param highlight - Whether the rows are a local command line drawn on the command bar.
+ * @returns One row per wrapped terminal line; empty text yields one empty row.
+ */
+export function plainRows(text, width, kind, highlight = false) {
+    const columns = Math.max(1, width);
+    const wrapped = wrapAnsi(text === '' ? ' ' : text, columns, { hard: true, trim: false });
+    return wrapped.split('\n').map(line => ({ text: line, kind, ...(highlight ? { highlight: true } : {}) }));
+}
 function wrapRows(text, width, kind, seq) {
     return wrapAnsi(text, width, { hard: true, trim: !['tool', 'success', 'error'].includes(kind) })
         .split('\n').map(text => ({ text, kind, seq }));

package/dist/shell/controller.d.ts

@@ -0,0 +1,67 @@
+/** One local command and the output retained for it. */
+export interface ShellBlock {
+    id: number;
+    command: string;
+    /** Retained output lines, oldest first. */
+    lines: string[];
+    /** Lines dropped from the front because the block exceeded its budget. */
+    dropped: number;
+    /** Durable sequence that was newest when the command started; the block is shown after it. */
+    anchor: number;
+    status: 'running' | 'exited';
+    /** Exit code, once the command ended; null when a signal ended it. */
+    code?: number | null;
+    signal?: string | null;
+    startedAt: number;
+    endedAt?: number;
+}
+/** What one shell controller needs from its owner. */
+export interface ShellHost {
+    /** Repaint after output or a status change. */
+    publish(): void;
+    /** Client working directory the command runs in. */
+    cwd(): string;
+    /** Environment for the child, already stripped of client credentials. */
+    env(): NodeJS.ProcessEnv;
+    /** Newest durable sequence of the selected session, so a block stays where it happened. */
+    anchor(): number;
+}
+/** Owns the `!` commands of this client process: one at a time, bounded, killable. */
+export declare class ShellController {
+    private readonly host;
+    readonly enabled: boolean;
+    private readonly blocks;
+    private readonly bytes;
+    private nextId;
+    private task;
+    private abort;
+    private lastPublish;
+    constructor(host: ShellHost, /** Whether `!` is allowed at all. */ enabled?: boolean);
+    /** Runs in creation order, oldest first; the newest is what the transcript shows at its end. */
+    get runs(): readonly ShellBlock[];
+    /** Whether a command is still running. */
+    get running(): boolean;
+    /** Start one command.
+     *
+     * One command runs at a time: a second `!` while the first is live is refused rather than queued,
+     * because the transcript shows a single result block and the reader can stop the first with Ctrl+C.
+     * @param command - Command line typed after `!`.
+     * @returns The block created for it.
+     */
+    start(command: string): ShellBlock;
+    /** Stop the running command: its process group gets SIGTERM, then SIGKILL after a grace period.
+     * @returns Whether a run was stopped.
+     */
+    cancel(): boolean;
+    /** One run's retained output, with dropped lines made explicit.
+     * @param id - Run to read; defaults to the newest.
+     * @returns The text, or undefined when the run is unknown.
+     */
+    output(id?: number): string | undefined;
+    /** Stop the running command and wait for it, so no child outlives this client. */
+    stop(): Promise<void>;
+    /** Append one output line, trimming the block to its budgets from the front. */
+    private append;
+    /** Repaint, at most once per interval unless the change is a status change. */
+    private publish;
+}

package/dist/shell/controller.js

@@ -0,0 +1,126 @@
+/** Local shell runs the reader started with `!`, kept as bounded blocks for inline display.
+ *
+ * A block is the command line plus its retained output. Output is capped by both lines and bytes, so
+ * a runaway command can only fill its block, and only the newest blocks are kept. Nothing here is
+ * durable: no host record, no session state, no file.
+ */
+import { setTimeout as delay } from 'node:timers/promises';
+import { runShell } from "./runner.js";
+/** Output lines one block keeps before it drops the oldest. */
+const BLOCK_LINES = 200;
+/** Output bytes one block keeps before it drops the oldest. */
+const BLOCK_BYTES = 64 * 1024;
+/** Runs kept for display; the newest always survives. */
+const BLOCK_LIMIT = 20;
+/** Fastest repaint cadence while output streams; status changes always publish. */
+const PUBLISH_INTERVAL_MS = 80;
+/** Owns the `!` commands of this client process: one at a time, bounded, killable. */
+export class ShellController {
+    host;
+    enabled;
+    blocks = [];
+    bytes = new WeakMap();
+    nextId = 1;
+    task;
+    abort;
+    lastPublish = 0;
+    constructor(host, /** Whether `!` is allowed at all. */ enabled = true) {
+        this.host = host;
+        this.enabled = enabled;
+    }
+    /** Runs in creation order, oldest first; the newest is what the transcript shows at its end. */
+    get runs() { return this.blocks; }
+    /** Whether a command is still running. */
+    get running() { return this.blocks.some(block => block.status === 'running'); }
+    /** Start one command.
+     *
+     * One command runs at a time: a second `!` while the first is live is refused rather than queued,
+     * because the transcript shows a single result block and the reader can stop the first with Ctrl+C.
+     * @param command - Command line typed after `!`.
+     * @returns The block created for it.
+     */
+    start(command) {
+        if (!this.enabled)
+            throw new Error('Shell commands are disabled (--no-shell or DSHT_NO_SHELL=1)');
+        if (this.task)
+            throw new Error('A shell command is already running; Ctrl+C stops it');
+        const block = { id: this.nextId++, command, lines: [], dropped: 0, status: 'running',
+            startedAt: Date.now(), anchor: this.host.anchor() };
+        this.blocks.push(block);
+        while (this.blocks.length > BLOCK_LIMIT)
+            this.blocks.shift();
+        this.bytes.set(block, 0);
+        const abort = new AbortController();
+        this.abort = abort;
+        this.publish(true);
+        const task = runShell(command, {
+            cwd: this.host.cwd(), env: this.host.env(), signal: abort.signal,
+            onLine: (line, stream) => this.append(block, line),
+        }).then(exit => {
+            block.status = 'exited';
+            block.code = exit.code;
+            block.signal = exit.signal;
+            block.endedAt = Date.now();
+        }, error => {
+            block.status = 'exited';
+            block.code = null;
+            this.append(block, `! ${error instanceof Error ? error.message : String(error)}`);
+        }).finally(() => {
+            if (this.abort === abort)
+                this.abort = undefined;
+            if (this.task === task)
+                this.task = undefined;
+            this.publish(true);
+        });
+        this.task = task;
+        return block;
+    }
+    /** Stop the running command: its process group gets SIGTERM, then SIGKILL after a grace period.
+     * @returns Whether a run was stopped.
+     */
+    cancel() {
+        if (!this.abort)
+            return false;
+        this.abort.abort();
+        return true;
+    }
+    /** One run's retained output, with dropped lines made explicit.
+     * @param id - Run to read; defaults to the newest.
+     * @returns The text, or undefined when the run is unknown.
+     */
+    output(id) {
+        const block = id === undefined ? this.blocks.at(-1) : this.blocks.find(item => item.id === id);
+        if (!block)
+            return undefined;
+        const head = block.dropped > 0 ? [`… ${block.dropped} earlier lines dropped …`] : [];
+        return [...head, ...block.lines].join('\n');
+    }
+    /** Stop the running command and wait for it, so no child outlives this client. */
+    async stop() {
+        this.cancel();
+        await this.task;
+        while (this.running)
+            await delay(20);
+    }
+    /** Append one output line, trimming the block to its budgets from the front. */
+    append(block, line) {
+        block.lines.push(line);
+        let bytes = (this.bytes.get(block) ?? 0) + line.length * 2;
+        while (block.lines.length > BLOCK_LINES || bytes > BLOCK_BYTES) {
+            if (block.lines.length === 1)
+                break;
+            bytes -= block.lines.shift().length * 2;
+            block.dropped++;
+        }
+        this.bytes.set(block, bytes);
+        this.publish(false);
+    }
+    /** Repaint, at most once per interval unless the change is a status change. */
+    publish(force) {
+        const now = Date.now();
+        if (!force && now - this.lastPublish < PUBLISH_INTERVAL_MS)
+            return;
+        this.lastPublish = now;
+        this.host.publish();
+    }
+}

package/dist/shell/index.d.ts

@@ -0,0 +1,5 @@
+/** Shell domain: the local `!` command runner and the bounded blocks it produces. */
+export { ShellController } from './controller.ts';
+export type { ShellBlock, ShellHost } from './controller.ts';
+export { runShell } from './runner.ts';
+export type { ShellExit, ShellRunOptions, ShellStream } from './runner.ts';

package/dist/shell/index.js

@@ -0,0 +1,3 @@
+/** Shell domain: the local `!` command runner and the bounded blocks it produces. */
+export { ShellController } from "./controller.js";
+export { runShell } from "./runner.js";

package/dist/shell/runner.d.ts

@@ -0,0 +1,28 @@
+/** Which pipe one line arrived on. */
+export type ShellStream = 'stdout' | 'stderr';
+/** How one command ended. */
+export interface ShellExit {
+    code: number | null;
+    signal: string | null;
+}
+/** One command's execution contract. */
+export interface ShellRunOptions {
+    /** Working directory; the client's own directory, not the host's. */
+    cwd: string;
+    /** Environment for the child; the caller strips client credentials first. */
+    env: NodeJS.ProcessEnv;
+    /** Cancels the run; the child's process group is terminated. */
+    signal: AbortSignal;
+    /** Receives every complete line, in arrival order across both pipes. */
+    onLine(line: string, stream: ShellStream): void;
+}
+/** Run one command through the operator's shell and stream its lines.
+ *
+ * Both pipes are merged into one line stream in arrival order. A line longer than the assemble
+ * budget is emitted once, truncated, and the remainder is discarded until the next newline, so a
+ * command that never emits one cannot grow the client's memory.
+ * @param command - Command line, exactly as typed after `!`.
+ * @param options - Directory, environment, cancellation and the line sink.
+ * @returns How the command ended.
+ */
+export declare function runShell(command: string, options: ShellRunOptions): Promise<ShellExit>;

package/dist/shell/runner.js

@@ -0,0 +1,108 @@
+/** Running one local shell command for the reader, and nothing else.
+ *
+ * `!cmd` executes on the machine this client runs on — the operator's laptop or a jump host — never
+ * on the host the agent works in. The host's shell belongs to the model's own tools; this module is
+ * a separate, local facility, and it is the only place in `src/` allowed to spawn a process.
+ */
+import { spawn } from 'node:child_process';
+/** Longest single output line kept while it is still being assembled. */
+const MAX_LINE_CHARS = 8 * 1024;
+/** How long a cancelled command may ignore SIGTERM before it is killed. */
+const KILL_GRACE_MS = 2_000;
+/** The interactive shell to run under, falling back to `sh` when `$SHELL` is unusable. */
+function shellPath() {
+    const chosen = process.env.SHELL;
+    return chosen !== undefined && chosen !== '' ? chosen : '/bin/sh';
+}
+/** Terminate one child's whole process group, so pipelines and background children die with it.
+ *
+ * The child is spawned detached, which gives it its own group; signalling the group is what makes
+ * cancellation behave like Ctrl+C in a terminal instead of leaving orphans holding the pipes.
+ * @param child - The spawned shell.
+ * @param signal - Signal to send the group.
+ */
+function signalGroup(child, signal) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch { /* already gone */ }
+    }
+}
+/** Run one command through the operator's shell and stream its lines.
+ *
+ * Both pipes are merged into one line stream in arrival order. A line longer than the assemble
+ * budget is emitted once, truncated, and the remainder is discarded until the next newline, so a
+ * command that never emits one cannot grow the client's memory.
+ * @param command - Command line, exactly as typed after `!`.
+ * @param options - Directory, environment, cancellation and the line sink.
+ * @returns How the command ended.
+ */
+export function runShell(command, options) {
+    return new Promise(resolve => {
+        const child = spawn(shellPath(), ['-c', command], {
+            cwd: options.cwd, env: options.env, detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const carry = { stdout: '', stderr: '' };
+        const discarding = { stdout: false, stderr: false };
+        let settled = false;
+        let graceTimer;
+        /** Emit one assembled line, keeping the partial remainder for the next chunk. */
+        const feed = (stream, chunk) => {
+            carry[stream] += chunk;
+            for (;;) {
+                const newline = carry[stream].indexOf('\n');
+                if (newline < 0)
+                    break;
+                const line = carry[stream].slice(0, newline);
+                carry[stream] = carry[stream].slice(newline + 1);
+                if (discarding[stream])
+                    discarding[stream] = false;
+                else
+                    options.onLine(line.replace(/\r$/, ''), stream);
+            }
+            if (carry[stream].length > MAX_LINE_CHARS) {
+                if (!discarding[stream]) {
+                    options.onLine(`${carry[stream].slice(0, MAX_LINE_CHARS)}…`, stream);
+                    discarding[stream] = true;
+                }
+                carry[stream] = '';
+            }
+        };
+        const flush = (stream) => {
+            if (carry[stream] !== '' && !discarding[stream])
+                options.onLine(carry[stream].replace(/\r$/, ''), stream);
+            carry[stream] = '';
+        };
+        const finish = (exit) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(graceTimer);
+            options.signal.removeEventListener('abort', onAbort);
+            flush('stdout');
+            flush('stderr');
+            resolve(exit);
+        };
+        const onAbort = () => {
+            signalGroup(child, 'SIGTERM');
+            graceTimer = setTimeout(() => { signalGroup(child, 'SIGKILL'); }, KILL_GRACE_MS);
+        };
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => feed('stdout', chunk));
+        child.stderr?.on('data', (chunk) => feed('stderr', chunk));
+        child.on('error', error => { options.onLine(`! ${error.message}`, 'stderr'); finish({ code: null, signal: null }); });
+        child.on('close', (code, signal) => finish({ code, signal }));
+        if (options.signal.aborted)
+            onAbort();
+        else
+            options.signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/ui/app.js

@@ -13,6 +13,7 @@ import { CostPanel } from "./dialogs/cost.js";
 import { StatusBar } from "./chat/status.js";
 import { ChatHeader } from "./chat/header.js";
 import { ChatViewport } from "./chat/viewport.js";
+import { mergeShellRuns } from "./chat/shell-view.js";
 import { Frozen } from "./frozen.js";
 import { CopyMode } from "./copy-mode.js";
 import { HelpPanel, HistoryDialog, ModelDialog, PickerScreen, QueueDialog, QueuedPreview, RemovalDialog, SearchResultsDialog, ThoughtsDialog } from "./dialogs/index.js";
@@ -360,6 +361,11 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
             operate(() => controller.showPicker('workspaces'));
             return;
         }
+        if (key.ctrl && _value === 'c' && input === '' && controller.shell.running) {
+            // A local command in the transcript is the most immediate thing Ctrl+C can stop.
+            controller.shell.cancel();
+            return;
+        }
         if (key.ctrl && _value === 'c') {
             // A draft clears first, exactly like a shell prompt; an empty draft still stops or exits.
             if (input !== '') {
@@ -416,6 +422,11 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
                 void controller.interrupt(true);
             return;
         }
+        if (key.escape && controller.shell.running && input === '' && !panelBlocksKeys && !pending && state.screen === 'chat') {
+            // The local command is the most immediate thing Esc can stop; the next press interrupts the agent.
+            controller.shell.cancel();
+            return;
+        }
         if (key.escape && state.screen === 'chat') {
             void controller.interrupt(true);
         }
@@ -516,6 +527,10 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
                 case 'queue':
                     controller.openQueue(true);
                     return;
+                case 'shell':
+                    controller.shell.start(submission.command);
+                    controller.setScroll(0);
+                    return;
                 case 'newSession':
                     await controller.createSession();
                     return;
@@ -663,21 +678,25 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
     ];
     const layout = useMemo(() => historyLayout(displayTranscript, width, reasoning, reasoningOverrides, liveReasoning), [displayTranscript, displayTranscript.version, width, reasoning, reasoningOverrides, liveReasoning]);
     const { length, first } = layout;
+    // Local `!` blocks live at the end of the transcript: not host records, not persisted, but they
+    // scroll with the conversation and are counted into its total so the viewport math stays honest.
+    const merged = useMemo(() => mergeShellRuns(layout, controller.shell.runs, width), [layout, controller, state.version, width]);
+    const totalRows = merged.total;
     const statusNotice = !['Connected', 'Idle', 'Running…', 'Responding…'].includes(state.status);
     const showHistoryHint = dialogOpen || displayTranscript.hasMore || !!historyWindow;
     const pageSize = Math.max(1, conversationRows - (showHistoryHint ? 1 : 0));
-    const previousView = useRef({ transcript: displayTranscript, session: state.session.record, count: length, first, folds: reasoningOverrides, liveReasoning });
+    const previousView = useRef({ transcript: displayTranscript, session: state.session.record, count: totalRows, first, folds: reasoningOverrides, liveReasoning });
     const previous = previousView.current;
     const prepended = previous.first !== undefined && first !== undefined && first < previous.first;
     const adjustedScroll = previous.session !== state.session.record ? 0
-        : scroll > 0 && previous.transcript === displayTranscript && !prepended && previous.folds === reasoningOverrides && previous.liveReasoning === liveReasoning ? Math.max(0, scroll + length - previous.count) : scroll;
-    const maxScroll = Math.max(0, length - pageSize);
+        : scroll > 0 && previous.transcript === displayTranscript && !prepended && previous.folds === reasoningOverrides && previous.liveReasoning === liveReasoning ? Math.max(0, scroll + totalRows - previous.count) : scroll;
+    const maxScroll = Math.max(0, totalRows - pageSize);
     const position = Math.min(adjustedScroll, maxScroll);
     useLayoutEffect(() => {
-        previousView.current = { transcript: displayTranscript, session: state.session.record, count: length, first, folds: reasoningOverrides, liveReasoning };
+        previousView.current = { transcript: displayTranscript, session: state.session.record, count: totalRows, first, folds: reasoningOverrides, liveReasoning };
         if (position !== scroll)
             controller.setScroll(position);
-    }, [state.session.record, displayTranscript, length, position, scroll, reasoningOverrides, liveReasoning]);
+    }, [state.session.record, displayTranscript, totalRows, position, scroll, reasoningOverrides, liveReasoning]);
     useLayoutEffect(() => {
         controller.pinHistory(!historyWindow && (position > 0 || thoughtList || historyQuery !== undefined && !contentSearch));
     }, [controller, historyWindow, position, thoughtList, historyQuery, contentSearch, state.session.record]);
@@ -802,8 +821,8 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
         scrollHistory(direction * 3); }, !copyMode && state.screen === 'chat', () => { if (!dialogOpen)
         setCopyMode(true); });
     const trailingGap = dialogOpen && length > 0 && layout.viewport(length - 1, length)[0]?.text === '' ? 1 : 0;
-    const end = Math.max(pageSize, length - position - trailingGap);
-    const visible = useMemo(() => layout.viewport(Math.max(0, end - pageSize), end), [layout, end, pageSize]);
+    const end = Math.max(pageSize, totalRows - position - trailingGap);
+    const visible = useMemo(() => merged.viewport(Math.max(0, end - pageSize), end), [merged, end, pageSize]);
     const liveThought = thoughtList && !historyWindow ? state.session.record.liveParts(width).find(part => part.kind === 'reasoning') : undefined;
     const thoughtEntries = thoughtList ? displayTranscript.thoughts : undefined;
     const thoughtChoices = useMemo(() => [...(thoughtEntries ?? [])].reverse().map(entry => ({

package/dist/ui/chat/history-view.js

@@ -12,6 +12,6 @@ import { useTheme } from "../theme/index.js";
  */
 export function HistoryViewport({ rows }) {
     const theme = useTheme();
-    return _jsx(Box, { flexDirection: "column", children: rows.map((row, index) => _jsx(Text, { color: theme.colors[row.kind], bold: row.bold, children: row.spans?.length ? row.spans.map((span, position) => _jsx(Text, { bold: span.bold, italic: span.italic, underline: span.underline, strikethrough: span.strikethrough, inverse: span.inverse, children: span.text }, position))
+    return _jsx(Box, { flexDirection: "column", children: rows.map((row, index) => _jsx(Text, { bold: row.bold, color: row.highlight ? theme.shell.foreground : theme.colors[row.kind], backgroundColor: row.highlight ? theme.shell.background : undefined, children: row.spans?.length ? row.spans.map((span, position) => _jsx(Text, { bold: span.bold, italic: span.italic, underline: span.underline, strikethrough: span.strikethrough, inverse: span.inverse, children: span.text }, position))
                 : row.text === '' ? ' ' : row.text }, index)) });
 }

package/dist/ui/chat/shell-view.d.ts

@@ -0,0 +1,34 @@
+import { type HistoryRow } from '../../session/history.ts';
+import type { ShellBlock } from '../../shell/index.ts';
+/** The part of a transcript layout this module needs to place a block. */
+export interface RowSource {
+    /** Number of host rows, live tail included. */
+    length: number;
+    /** Host rows in a range. */
+    viewport(start: number, end: number): HistoryRow[];
+    /** Projected messages in ascending sequence order. */
+    messages: readonly {
+        seq: number;
+    }[];
+    /** Row index where each visible message starts. */
+    offsets: ReadonlyMap<number, number>;
+}
+/** Rows for one run: the command bar, then its wrapped and indented output.
+ * @param run - Block from the shell controller.
+ * @param width - Available terminal columns.
+ * @returns Rows in display order.
+ */
+export declare function blockRows(run: ShellBlock, width: number): HistoryRow[];
+/** Splice every retained block into a transcript layout.
+ *
+ * Equal anchors keep creation order, and an anchor older than a block already placed is clamped to
+ * it, so the merged stream stays ordered even as history is paged in behind the reader.
+ * @param layout - Transcript layout to merge with.
+ * @param runs - Blocks from the shell controller, oldest first.
+ * @param width - Available terminal columns.
+ * @returns The merged row count and a reader over a merged range.
+ */
+export declare function mergeShellRuns(layout: RowSource, runs: readonly ShellBlock[], width: number): {
+    total: number;
+    viewport(start: number, end: number): HistoryRow[];
+};

package/dist/ui/chat/shell-view.js

@@ -0,0 +1,111 @@
+/** Local `!` blocks as transcript rows: a highlighted command bar, then its indented output.
+ *
+ * A block is spliced into the conversation where it happened — after the newest record the session
+ * had when the command started — so it scrolls away like any message instead of sitting pinned to
+ * the bottom of the screen.
+ */
+import stringWidth from 'string-width';
+import { plainRows } from "../../session/history.js";
+/** First output row's marker, so a block reads as the command's result. */
+const MARKER = '  ⎿  ';
+/** Rows after the first, aligned under the marker. */
+const GUTTER = '   ';
+/** Rows for one run: the command bar, then its wrapped and indented output.
+ * @param run - Block from the shell controller.
+ * @param width - Available terminal columns.
+ * @returns Rows in display order.
+ */
+export function blockRows(run, width) {
+    const reserve = Math.max(stringWidth(MARKER), stringWidth(GUTTER));
+    const rows = [{ text: `! ${run.command}`, kind: 'shell', bold: true, highlight: true }];
+    const body = [
+        ...(run.dropped > 0 ? [`… ${run.dropped} earlier lines dropped …`] : []),
+        ...run.lines,
+    ];
+    if (!body.length)
+        body.push(run.status === 'running' ? 'running…' : '(no output)');
+    body.forEach((line, index) => {
+        const wrapped = plainRows(line, Math.max(8, width - reserve), 'shell');
+        wrapped.forEach((row, position) => {
+            rows.push({ ...row, text: `${index === 0 && position === 0 ? MARKER : GUTTER}${row.text}` });
+        });
+    });
+    if (run.status === 'exited' && (run.signal != null || (run.code ?? 0) !== 0)) {
+        rows.push({ text: `${GUTTER}exit ${run.signal ?? run.code}`, kind: 'muted' });
+    }
+    return rows;
+}
+/** Host row index where a block anchored at `anchor` belongs.
+ *
+ * It goes after every row of the newest message it followed, which is the start of the next message,
+ * or the end of the layout when nothing newer is loaded.
+ * @param layout - Transcript layout to place into.
+ * @param anchor - Durable sequence the command followed.
+ * @returns Host row index.
+ */
+function rowAfter(layout, anchor) {
+    let low = 0, high = layout.messages.length;
+    while (low < high) {
+        const mid = (low + high) >> 1;
+        if (layout.messages[mid].seq <= anchor)
+            low = mid + 1;
+        else
+            high = mid;
+    }
+    if (low >= layout.messages.length)
+        return layout.length;
+    return layout.offsets.get(layout.messages[low].seq) ?? layout.length;
+}
+/** Splice every retained block into a transcript layout.
+ *
+ * Equal anchors keep creation order, and an anchor older than a block already placed is clamped to
+ * it, so the merged stream stays ordered even as history is paged in behind the reader.
+ * @param layout - Transcript layout to merge with.
+ * @param runs - Blocks from the shell controller, oldest first.
+ * @param width - Available terminal columns.
+ * @returns The merged row count and a reader over a merged range.
+ */
+export function mergeShellRuns(layout, runs, width) {
+    const placements = [];
+    let cursor = 0;
+    for (const run of runs) {
+        const at = Math.max(cursor, Math.min(layout.length, rowAfter(layout, run.anchor)));
+        placements.push({ at, rows: blockRows(run, width) });
+        cursor = at;
+    }
+    // Segments alternate host rows and block rows in merged index order.
+    const segments = [];
+    let merged = 0, host = 0;
+    for (const placement of placements) {
+        if (placement.at > host) {
+            segments.push({ from: merged, count: placement.at - host, host });
+            merged += placement.at - host;
+            host = placement.at;
+        }
+        segments.push({ from: merged, count: placement.rows.length, rows: placement.rows });
+        merged += placement.rows.length;
+    }
+    if (host < layout.length)
+        segments.push({ from: merged, count: layout.length - host, host });
+    const total = merged + Math.max(0, layout.length - host);
+    return {
+        total,
+        viewport(start, end) {
+            const rows = [];
+            for (const segment of segments) {
+                const segmentStart = segment.from, segmentEnd = segment.from + segment.count;
+                if (segmentEnd <= start || segmentStart >= end)
+                    continue;
+                const from = Math.max(0, start - segmentStart);
+                const to = Math.min(segment.count, end - segmentStart);
+                if (to <= from)
+                    continue;
+                if (segment.rows)
+                    rows.push(...segment.rows.slice(from, to));
+                else
+                    rows.push(...layout.viewport(segment.host + from, segment.host + to));
+            }
+            return rows;
+        },
+    };
+}

package/dist/ui/commands/parse.d.ts

@@ -56,6 +56,11 @@ export type Submission = {
 } | {
     kind: 'hostCommand';
     line: string;
+}
+/** A local `!` command, run on this machine rather than the host. */
+ | {
+    kind: 'shell';
+    command: string;
 } | {
     kind: 'export';
     destination?: string;

package/dist/ui/commands/parse.js

@@ -17,6 +17,15 @@ export function classifySubmission(raw, context) {
     const value = raw.trim();
     if (!value)
         return { kind: 'ignore' };
+    // `!` runs on the machine this client is on; it never reaches the host or the model.
+    if (value.startsWith('!')) {
+        const command = value.slice(1).trim();
+        if (!command)
+            return { kind: 'error', message: 'Type a command after !' };
+        if (context.screen !== 'chat')
+            return { kind: 'error', message: 'Select a session first' };
+        return { kind: 'shell', command };
+    }
     if (value === '/copy')
         return { kind: 'copy' };
     if (value === '/quit')

package/dist/ui/theme/index.d.ts

@@ -3,6 +3,11 @@ import type { RowKind } from '../../session/history.ts';
 export interface Theme {
     name: string;
     colors: Record<RowKind, string>;
+    /** Bar drawn behind a local `!` command line, so it reads as this machine rather than the agent. */
+    shell: {
+        background: string;
+        foreground: string;
+    };
     status: Record<'working' | 'ready' | 'offline' | 'model' | 'cost' | 'context' | 'warning' | 'critical' | 'usage', string>;
     accent: string;
     border: string;

package/dist/ui/theme/index.js

@@ -4,7 +4,8 @@ import { createContext, useContext } from 'react';
 export const mocha = {
     name: 'Catppuccin Mocha',
     colors: { user: '#89b4fa', assistant: '#a6e3a1', context: '#f9e2af', text: '#cdd6f4',
-        reasoning: '#cba6f7', tool: '#89dceb', success: '#a6e3a1', error: '#f38ba8', muted: '#a6adc8' },
+        reasoning: '#cba6f7', tool: '#89dceb', success: '#a6e3a1', error: '#f38ba8', muted: '#a6adc8', shell: '#a6adc8' },
+    shell: { background: '#cdd6f4', foreground: '#1e1e2e' },
     status: { working: '#f9e2af', ready: '#a6e3a1', offline: '#f38ba8', model: '#cba6f7',
         cost: '#89dceb', context: '#a6e3a1', warning: '#f9e2af', critical: '#f38ba8', usage: '#a6adc8' },
     accent: '#cba6f7', border: '#6c7086',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itookit/dsht",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "type": "module",
   "description": "Remote-first TUI for DeepSeek Harness with SSH-friendly mobile access and request-level cost tracking",
   "engines": {