@xmoon76/dsh-pi-tui 0.3.1 → 0.3.3

package/README.md

@@ -336,17 +336,30 @@ the Advanced/Unstable roadmap).
   pinned earlier** (`/rename` is an alias).
 - `/tasks` — the merged task browser: background jobs AND subagents in one
   searchable list (type to filter rows by kind/label/status — `subagent`,
-  `bash`, `failed`…). `Enter` opens the detail (child transcript for a
-  subagent, status viewer for a job), `i` interrupts the selected subagent.
-  `/subagents` is an alias.
+  `bash`, `failed`…). Subagent rows show their mode as part of the label
+  (`subagent · <label> · continuable` / `… · one-shot`) — you know before
+  Enter whether the viewer will be interactive. `Enter` opens the detail
+  (child viewer for a subagent, status viewer for a job), `i` interrupts
+  the selected subagent. `/subagents` is an alias.
 - `/yolo` — switch to `danger-full-access` (alias of `/permission danger-full-access`).
 - `/status` — show the current session's stats and identity (turn counts,
   token usage, workspace, installed dsh version).
+- `/rewind` — fork this conversation from an earlier user turn: the picker
+  lists every completed user prompt (newest first), and choosing one creates
+  a new child session whose history ends right before that turn, then
+  restores the selected prompt into the editor for editing. The original
+  session is never modified and stays reachable through `/sessions`;
+  **workspace and external side effects (files, shell, APIs) are not
+  reverted.** The same picker opens with `Esc Esc` on an empty editor.
 - `/preset`, `/model`, `/settings`, `/export`, `/fork` — see
   `dsh --profile pi-tui`'s command autocomplete (`/` + Tab).
 
 ## Keybindings (selection)
 
+- `Esc Esc` — conversation rewind (on an empty editor while idle): open the
+  rewind picker and fork from an earlier user turn. One `Esc` while the
+  agent is busy still cancels the active turn/tool/shell command; with a
+  non-empty draft the double-Esc keeps its historical cancel behavior.
 - `Ctrl+F` — toggle transcript search (the `/search <query>` overlay; a
   second press closes it).
 - `Shift+Tab` — cycle the permission preset (read-only → workspace-write →
@@ -366,10 +379,20 @@ the Advanced/Unstable roadmap).
   fallback otherwise). The literal `@path` is submitted and the model reads
   the file itself. With background work running, an empty editor's `↓` opens
   the same merged task browser as `/tasks`:
-  - **subagent rows** (live continuable children) — `Enter` opens the child's
-    transcript read-only (`Esc` returns); `i` interrupts the selected child.
-    They never register jobs records, so this browser is their only glanceable
-    home.
+  - **subagent rows** (live children, labeled with their catalog mode:
+    `continuable` or `one-shot`) — `Enter` opens the child's viewer:
+    a **continuable** child's viewer is **interactive** — type a
+    follow-up and press Enter, and it is delivered as the child's NEXT
+    turn through `ctx.subagents.followup` (FIFO — a running child is
+    never interrupted or steered; an inactive child cold-resumes
+    automatically), while `Esc` returns to your session. A **one-shot**
+    child's viewer stays **read-only** (`Esc` returns; the editor shows
+    the read-only placeholder). While a viewer is open the footer
+    switches to the CHILD's own identity (`[subagent · continuable]`
+    badge, label, activity, cwd, the child's own turns/steps/stats) and
+    returns to your session's on exit. `i` interrupts the selected
+    child. They never register job records, so this browser is their
+    only glanceable home.
   - **job rows** (bash and one-shot subagent jobs) — `Enter` shows the status
     viewer only: a bash job's output read cursor belongs to the model's
     `job_output`, and a one-shot subagent job record carries no child session

package/README.zh-CN.md

@@ -299,18 +299,28 @@ SDK。原始终端访问、pre-host 输入拦截与完整输入所有权**不属
   生成标题——这会覆盖当前标题,包括你之前固定的标题**(`/rename` 是
   别名)。
 - `/tasks` — 合并任务浏览器:后台 job 与子代理在同一个可搜索列表中
-  (直接输入过滤行——`subagent`、`bash`、`failed`…)。`Enter` 打开详情
-  (子代理为子转录,job 为状态查看器),`i` 中断选中的子代理。
+  (直接输入过滤行——`subagent`、`bash`、`failed`…)。子代理行把 mode
+  写进主标签(`subagent · <label> · continuable` / `… · one-shot`),
+  按下 `Enter` 之前就能知道查看器是否可交互。`Enter` 打开详情
+  (子代理为子查看器,job 为状态查看器),`i` 中断选中的子代理。
   `/subagents` 是别名。
 - `/yolo` — 切换到 `danger-full-access`(`/permission danger-full-access`
   的别名)。
 - `/status` — 显示当前会话的统计与身份信息(回合数、token 用量、
   工作区、已安装的 dsh 版本)。
+- `/rewind` — 从更早的用户回合 fork 当前对话:选择器列出每个已完成
+  的用户提示(最新在上),选中一个会创建一个新的子会话,其历史恰好
+  止于该回合之前,并把选中的提示回填到编辑器供修改。原会话从不被
+  修改,仍可通过 `/sessions` 回到;**工作区与外部副作用(文件、shell、
+  API)不会回滚。** 空编辑器下按 `Esc Esc` 也会打开同一个选择器。
 - `/preset`、`/model`、`/settings`、`/export`、`/fork` —
   见 `dsh --profile pi-tui` 的命令自动补全(`/` + Tab)。
 
 ## 快捷键(节选)
 
+- `Esc Esc` — 对话 rewind(空闲且编辑器为空时):打开 rewind 选择器,
+  从更早的用户回合 fork。agent 忙碌时按一次 `Esc` 仍只取消当前
+  回合/工具/shell 命令;草稿非空时双击 Esc 保持原有的取消语义。
 - `Ctrl+F` — 切换转录搜索(`/search <query>` 覆盖层;再按一次关闭)。
 - `Shift+Tab` — 循环切换权限预设(read-only → workspace-write →
   danger-full-access);页脚的模式槽位会为每个预设显示徽章
@@ -327,9 +337,16 @@ SDK。原始终端访问、pre-host 输入拦截与完整输入所有权**不属
   (`fd` 在 PATH 上时以其为后端,否则使用内置的递归回退)。字面
   `@path` 会被提交,由模型自行读取文件。有后台工作时,空编辑器的 `↓`
   会打开与 `/tasks` 相同的合并任务浏览器:
-  - **子代理行**(可继续的实时子任务)——`Enter` 以只读方式打开子代理
-    的转录(`Esc` 返回);`i` 中断选中的子代理。它们从不注册 job 记录,
-    所以此浏览器是它们唯一可一览的归宿。
+  - **子代理行**(实时子任务,标签携带目录 mode:`continuable` 或
+    `one-shot`)——`Enter` 打开子代理查看器:**continuable** 子代理的
+    查看器是**可交互的**——输入后续消息并回车,它会作为子代理的
+    **下一回合**通过 `ctx.subagents.followup` 投递(FIFO——运行中的
+    子代理不会被中断或 steer;非活跃的子代理会自动冷恢复),`Esc` 返回
+    主会话。**one-shot** 子代理的查看器保持**只读**(`Esc` 返回,编辑器
+    显示只读占位符)。查看器打开期间,页脚切换为**子代理自己的身份**
+    (`[subagent · continuable]` 徽章、标签、activity、cwd 与子代理自己的
+    turns/steps/stats),退出后恢复主会话页脚。`i` 中断选中的子代理。
+    它们从不注册 job 记录,所以此浏览器是它们唯一可一览的归宿。
   - **job 行**(bash 与一次性子代理 job)——`Enter` 只显示状态查看器:
     bash job 的输出读取游标属于模型的 `job_output`,而一次性子代理 job
     记录不带子会话 id,因此子代理 job 的转录需通过 `/tasks` 按标签

package/dist/builtins.mjs

@@ -1,5 +1,5 @@
 import { TUI_STARTUP_SERVICE } from "./startup.mjs";
-import { A as dshVersion, F as PI_TUI_EXTENSIONS_SERVICE } from "./src-ClAKiW0z.mjs";
+import { H as PI_TUI_EXTENSIONS_SERVICE, L as dshVersion } from "./src-Txng8gIG.mjs";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 //#region src/builtins.ts

package/dist/extension/advanced.d.mts

@@ -1,4 +1,4 @@
-import { E as PiTuiApiInfo, T as NormalizedKey, _ as ExtensionTier, at as TuiOverlayOptions, h as EditorSnapshot, v as ExtensionView } from "../public-types-2omeXG8d.mjs";
+import { E as PiTuiApiInfo, T as NormalizedKey, _ as ExtensionTier, at as TuiOverlayOptions, h as EditorSnapshot, v as ExtensionView } from "../public-types-CZz5_arj.mjs";
 
 //#region src/extension/advanced-types.d.ts
 /** API level of the advanced tier. Bumped only on advanced breaking changes. */

package/dist/extension/unstable.d.mts

@@ -1,4 +1,4 @@
-import { E as PiTuiApiInfo, _ as ExtensionTier, at as TuiOverlayOptions } from "../public-types-2omeXG8d.mjs";
+import { E as PiTuiApiInfo, _ as ExtensionTier, at as TuiOverlayOptions } from "../public-types-CZz5_arj.mjs";
 
 //#region src/extension/unstable-types.d.ts
 /** API level of the unstable tier. Bumped only on unstable breaking changes. */

package/dist/extensions.d.mts

@@ -1,4 +1,4 @@
-import { $ as TuiKeybindingHandle, A as RegistrationHandle, B as ToolPresentationSnapshot, C as MarkdownView, D as PiTuiCapability, E as PiTuiApiInfo, F as StackView, G as TuiAutocompleteRegistryView, H as TuiAutocompleteItem, I as StyledSpan, J as TuiCommandBridgeSnapshot, K as TuiAutocompleteSuggestions, L as SurfaceSnapshot, M as RowsView, N as SessionSnapshot, O as PiTuiSlotName, P as SpacerView, Q as TuiKeybindingContribution, R as SurfaceStateValues, S as InputWidget, T as NormalizedKey, U as TuiAutocompleteProvider, V as TuiAction, W as TuiAutocompleteQuery, X as TuiCommandContribution, Y as TuiCommandBridgeView, Z as TuiCommandHandle, _t as TuiThemeRegistryView, a as ContributionHealth, at as TuiOverlayOptions, b as FrameView, c as DockItem, ct as TuiRendererRegistryView, d as EditorHost, dt as TuiSettingsRegistrySnapshot, et as TuiKeybindingRegistrySnapshot, f as EditorHostAction, ft as TuiSettingsRegistryView, g as ExtensionEditor, gt as TuiThemeRegistrySnapshot, h as EditorSnapshot, ht as TuiThemeHandle, i as AutocompleteProviderContribution, it as TuiOverlayHandle, j as RegistrationSpec, k as PiTuiSlotSemantic, l as EditorContribution, lt as TuiSettingContribution, m as EditorInputEvent, mt as TuiThemeContribution, n as ActivitySnapshot, nt as TuiLocalCommandHandler, o as ContributionRecord, ot as TuiRendererHandle, p as EditorHostActionResult, pt as TuiSizeValue, q as TuiColorPalette, r as AutocompleteHandle, rt as TuiMessageRendererContribution, s as ContributionState, st as TuiRendererRegistrySnapshot, t as API_VERSION, tt as TuiKeybindingRegistryView, u as EditorHandle, ut as TuiSettingHandle, v as ExtensionView, vt as TuiToolRendererContribution, w as MessagePresentationSnapshot, x as HeaderBadge, y as FooterSegment, yt as describeKey, z as TextView } from "./public-types-2omeXG8d.mjs";
+import { $ as TuiKeybindingHandle, A as RegistrationHandle, B as ToolPresentationSnapshot, C as MarkdownView, D as PiTuiCapability, E as PiTuiApiInfo, F as StackView, G as TuiAutocompleteRegistryView, H as TuiAutocompleteItem, I as StyledSpan, J as TuiCommandBridgeSnapshot, K as TuiAutocompleteSuggestions, L as SurfaceSnapshot, M as RowsView, N as SessionSnapshot, O as PiTuiSlotName, P as SpacerView, Q as TuiKeybindingContribution, R as SurfaceStateValues, S as InputWidget, T as NormalizedKey, U as TuiAutocompleteProvider, V as TuiAction, W as TuiAutocompleteQuery, X as TuiCommandContribution, Y as TuiCommandBridgeView, Z as TuiCommandHandle, _t as TuiThemeRegistryView, a as ContributionHealth, at as TuiOverlayOptions, b as FrameView, c as DockItem, ct as TuiRendererRegistryView, d as EditorHost, dt as TuiSettingsRegistrySnapshot, et as TuiKeybindingRegistrySnapshot, f as EditorHostAction, ft as TuiSettingsRegistryView, g as ExtensionEditor, gt as TuiThemeRegistrySnapshot, h as EditorSnapshot, ht as TuiThemeHandle, i as AutocompleteProviderContribution, it as TuiOverlayHandle, j as RegistrationSpec, k as PiTuiSlotSemantic, l as EditorContribution, lt as TuiSettingContribution, m as EditorInputEvent, mt as TuiThemeContribution, n as ActivitySnapshot, nt as TuiLocalCommandHandler, o as ContributionRecord, ot as TuiRendererHandle, p as EditorHostActionResult, pt as TuiSizeValue, q as TuiColorPalette, r as AutocompleteHandle, rt as TuiMessageRendererContribution, s as ContributionState, st as TuiRendererRegistrySnapshot, t as API_VERSION, tt as TuiKeybindingRegistryView, u as EditorHandle, ut as TuiSettingHandle, v as ExtensionView, vt as TuiToolRendererContribution, w as MessagePresentationSnapshot, x as HeaderBadge, y as FooterSegment, yt as describeKey, z as TextView } from "./public-types-CZz5_arj.mjs";
 import { Context, Service } from "@deepseek-ai/cordis";
 
 //#region src/extension/service.d.ts

package/dist/extensions.mjs

@@ -1,3 +1,3 @@
 import "./startup.mjs";
-import { F as PI_TUI_EXTENSIONS_SERVICE, I as API_VERSION, L as describeKey, M as apply, N as inject, P as name } from "./src-ClAKiW0z.mjs";
+import { B as inject, H as PI_TUI_EXTENSIONS_SERVICE, U as API_VERSION, V as name, W as describeKey, z as apply } from "./src-Txng8gIG.mjs";
 export { API_VERSION, PI_TUI_EXTENSIONS_SERVICE, apply, describeKey, inject, name };

package/dist/index.d.mts

@@ -1,9 +1,90 @@
+import { V as TuiAction } from "./public-types-CZz5_arj.mjs";
 import z from "@deepseek-ai/schemastery";
 import { Agent, ModelSelectionRef } from "@deepseek-ai/dsh-agent";
 import { ContentBlock } from "@deepseek-ai/dsh-llm";
 import { SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
 import { CommandDescriptor } from "@deepseek-ai/dsh-commands";
 import { Context } from "@deepseek-ai/cordis";
+//#region src/image/admission.d.ts
+/** Structural subset of `ImageAttachmentRef`. */
+interface ImageAttachmentRefLike {
+  readonly attachmentId: string;
+  readonly mediaType: ImageMediaType;
+  readonly bytes: number;
+  readonly width: number;
+  readonly height: number;
+  readonly name?: string;
+}
+//#endregion
+//#region src/image/types.d.ts
+/**
+ * Image draft vocabulary for the TUI input pipeline (plan M1).
+ *
+ * The draft layer is TUI-owned: it stages clipboard/file bytes until a
+ * submission turns them into durable `ImageAttachmentRef`s through the dsh
+ * attachment service. Nothing in this module persists; the durable boundary
+ * is the harness's `ctx.attachments.saveImages()`.
+ *
+ * The media-type union mirrors `@deepseek-ai/dsh-attachment`'s
+ * `ImageMediaType` structurally, so drafts flow into the harness without a
+ * runtime dependency on the attachment package (AGENTS.md decision 7:
+ * structural typing for dsh services).
+ * @module @xmoon76/dsh-pi-tui/image/types
+ */
+/** Raster media types accepted by the TUI image intake. */
+type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** Per-TUI draft image identity; only meaningful inside one TUI run. */
+type DraftImageId = number;
+/** Where a staged image's bytes came from. */
+type DraftImageSource = {
+  readonly type: 'clipboard';
+} | {
+  readonly type: 'path';
+  readonly path: string;
+}
+/** The image was pulled back from a queued message: its bytes are ALREADY
+ * durable with the harness (the recalled ref) — the draft holds no local
+ * copy and re-submitting reuses the ref instead of re-uploading. */
+| {
+  readonly type: 'recalled';
+};
+/**
+ * One image staged in the editor draft. The draft holds the raw bytes so
+ * clipboard and path entries share one shape and a submit never depends on
+ * the source file still existing (plan §5.1). A RECALLED draft (pulled
+ * back from the queue) instead carries the durable `ImageAttachmentRef`
+ * and NO local bytes — the bytes stay in harness storage and re-submitting
+ * reuses the ref.
+ */
+interface DraftImage {
+  /** Per-TUI draft identity (the `#N` of the placeholder). */
+  readonly id: DraftImageId;
+  readonly kind: 'image';
+  readonly source: DraftImageSource;
+  /** Exact encoded bytes, held only for the draft lifetime. Empty for a
+   * recalled draft (its bytes live in harness storage). */
+  readonly bytes: Uint8Array;
+  readonly mediaType: ImageMediaType;
+  /** Intrinsic encoded width in pixels. */
+  readonly width: number;
+  /** Intrinsic encoded height in pixels. */
+  readonly height: number;
+  /** Exact encoded byte length (`bytes.byteLength` for local drafts; the
+   * durable ref's recorded `bytes` for recalled drafts). */
+  readonly byteLength: number;
+  /** Optional display name (basename for path sources), never a path. */
+  readonly name?: string;
+  /** The canonical editor placeholder text for this draft. */
+  readonly placeholder: string;
+  /** The durable ref this draft reuses on submit; present ONLY for
+   * recalled drafts (already-durable images are never re-uploaded). */
+  readonly recalledRef?: ImageAttachmentRefLike;
+}
+/** The store surface the placeholder expansion needs (structural). */
+interface DraftImageStoreLike {
+  values(): readonly DraftImage[];
+}
+//#endregion
 //#region src/diag.d.ts
 interface Diag {
   debug(message: string, fields?: Record<string, unknown>): void;
@@ -15,6 +96,12 @@ interface Diag {
 }
 //#endregion
 //#region src/tui-app.d.ts
+/** The compaction lifecycle phase the working row advertises: idle (no
+ * compaction), summarizing (compaction/start seen, the summary is being
+ * generated), or applying (the summary landed, the compacted surface is
+ * being committed). Derived by the runner from compaction/start →
+ * compaction/summary → compaction/end (foldCompactionEvent). */
+type CompactionPhase = 'idle' | 'summarizing' | 'applying';
 /** One queued inbox row for the queue pane (mirrors the agent Inbox's lists). */
 interface QueueItem {
   /** The pending message id (agent inbox identity). */
@@ -159,6 +246,23 @@ declare const SESSIONLESS_COMMANDS: Set<string>;
  * body — there is no command-execution wire for skills.
  */
 declare const LOCAL_COMMANDS: Set<string>;
+/**
+ * Command semantics matrix (plan §19.3/M12): a LOCAL command line carrying a
+ * staged image placeholder is REJECTED — local commands are pure UI
+ * controls, never LLM prompts. AGENT-FACING input (plain prompts AND
+ * per-skill slash invocations like `/grilling`) SUPPORTS images: the skill
+ * wrapper builds its message through the same prepared-input path, so an
+ * image-bearing skill line is a real multimodal prompt (review finding 4).
+ * There is never a silent drop.
+ * @param parsed - the parsed slash command, undefined for a plain prompt.
+ * @param text - the submission text.
+ * @param store - the live draft store.
+ * @param isLocal - whether the command name is a LOCAL (TUI-owned/UI)
+ *   command; skill names answer false.
+ */
+declare function commandRejectsImages(parsed: {
+  name: string;
+} | undefined, text: string, store: DraftImageStoreLike, isLocal: (name: string) => boolean): boolean;
 /**
  * The AUTHORITATIVE host-owned command catalog (P1-04): every command name
  * the TUI registers itself (registerTuiCommands in commands.ts) plus the
@@ -183,7 +287,23 @@ declare const HOST_COMMAND_CATALOG: ReadonlySet<string>;
  */
 declare function shouldSteerOnEnter(parsed: {
   name: string;
+  rawInput?: string;
 } | undefined, running: boolean, busyEnter: string | undefined, forceQueue: boolean, isDynamicLocal?: (name: string) => boolean): boolean;
+/**
+ * Normalize an explicit `/skill <name> <args>` invocation to the skill's
+ * own slash line `/<name> <args>` (review finding 2). The harness's
+ * explicit skill gesture scans for `/<skill-name>` — it would extract
+ * `skill` from a raw `/skill grilling ...` line and never inject the
+ * grilling body. The command handler already performs this conversion
+ * (`loadSkill` builds `'/' + skill.name + ' ' + args`); the busy-Enter
+ * steer path must use the SAME normalized line so the body injects and
+ * any image placeholders ride along.
+ * @param text - the submitted line.
+ * @returns the normalized `/<name> <args>` line, or undefined when the
+ *   line is not an explicit skill invocation (plain prompt, other
+ *   commands, or the bare `/skill` picker).
+ */
+declare function normalizeSkillInvocation(text: string): string | undefined;
 /**
  * The advertised-claim miss decision (pure, exported for the headless
  * suite): a slash input whose name was advertised by the completion list at
@@ -198,11 +318,94 @@ declare function shouldSteerOnEnter(parsed: {
 declare function shouldConsumeAdvertisedMiss(execution: {
   readonly result: unknown;
 } | undefined, wasAdvertised: boolean): boolean;
+/** The live-agent surface {@link interruptAgent} needs (structural — the
+ * TUI never imports the agent runtime for this call). */
+interface InterruptAgentLike {
+  readonly status: string;
+  cancel(cause: {
+    kind: 'user';
+  }, options?: {
+    keepInbox?: boolean;
+  }): void;
+}
+/**
+ * Interrupt the live agent (web Stop parity): abort the current
+ * turn/tool run while PRESERVING the pending queue. dsh's DEFAULT
+ * `cancel()` clears queued AND steering input, so a bare cancel would
+ * destroy everything the user queued with Ctrl+S / queue-mode Enter —
+ * the Esc-interrupt semantic is "stop the current thinking", never
+ * "drop the queue". `keepInbox: true` parks the preserved work; dsh's
+ * cancel is a documented no-op when nothing is active, so an idle
+ * interrupt (double-Esc while idle) is harmless and still aborts a
+ * local shell / maintenance task through the caller.
+ *
+ * NOTE (upstream dependency): dsh currently PARKS the preserved queue
+ * after an abort — the "Esc with a queue continues immediately" UX
+ * needs an upstream `wakePending`/`continueInbox` capability (not yet
+ * in dsh). A TUI-side emulation (remove + re-send a queue message)
+ * would fabricate durable discarded/inserted events in the session
+ * log, which the design explicitly rejects — the parked queue is the
+ * agreed web-parity behavior until upstream lands the capability.
+ */
+declare function interruptAgent(agent: InterruptAgentLike | undefined): void;
 /** One unsettled subagent delegation, in tool/call order. */
 interface PendingSubagentCall {
   readonly callId: string;
   readonly description: string;
 }
+/**
+ * The async viewer-OPEN invalidation token (pure, exported for the headless
+ * suite — the runner closure itself is not drivable in the headless tests,
+ * so the lifecycle rule is tested through these token semantics). An open
+ * request captures a token; EVERY viewer session change — opening another
+ * child, leaving the viewer (Esc), or a session swap (which routes through
+ * exitView) — invalidates the token, so a slow transcript inspection can
+ * never commit an obsolete child over the current surface. Invalidation is
+ * unconditional: an exit that finds NO mounted viewer still invalidates,
+ * because the open is exactly then still in flight (round-5 finding).
+ */
+interface ViewerOpenToken {
+  /** The current token value (bumped by every open and every invalidate). */
+  readonly current: number;
+  /** Start one async open; returns the request's token. */
+  open(): number;
+  /** Invalidate every in-flight open (a viewer session change). */
+  invalidate(): void;
+  /** Whether a request may still commit. */
+  isCurrent(request: number): boolean;
+}
+declare function createViewerOpenToken(): ViewerOpenToken;
+/**
+ * Session-swap viewer teardown (pure, exported for the headless suite —
+ * the runner closure is not headless-drivable, so the rule is pinned
+ * through this seam). A session swap must do BOTH: invalidate any
+ * in-flight viewer OPEN — UNCONDITIONALLY, because the open may still be
+ * loading when nothing is mounted yet, and the swap must still cancel it
+ * (round-6 finding) — and close a MOUNTED viewer when there is one.
+ * @param token - the shared viewer-open token.
+ * @param mounted - whether a viewer is currently mounted.
+ * @param closeMounted - closes the mounted viewer (a no-op when unmounted).
+ * @returns whether a mounted viewer was closed.
+ */
+declare function teardownViewerForSessionSwap(token: ViewerOpenToken, mounted: boolean, closeMounted: () => void): boolean;
+/**
+ * The viewer capability gate for SEMANTIC plugin actions (pure, exported
+ * for the headless suite — the runner closure is not drivable there).
+ * While a subagent viewer is open, only actions that stay CHILD- or
+ * SURFACE-local are allowed; every action with PARENT-session side
+ * effects (steer, cancel/interrupt, permission cycling, the main
+ * transcript search) is blocked, so a plugin keybinding can never
+ * interrupt/steer/reconfigure the parent from inside the viewer. The
+ * raw-key viewer guard already consumes the parent chords — this gate
+ * closes the plugin-keybinding path, the only other way a semantic
+ * action reaches the runner.
+ * @param action - the semantic action the plugin requested.
+ * @param viewer - the open viewer (mode), or undefined when no viewer.
+ * @returns whether the runner may execute the action.
+ */
+declare function viewerActionCapability(action: TuiAction, viewer: {
+  mode: 'one-shot' | 'continuable';
+} | undefined): boolean;
 /**
  * Match the child a user is about to view against the unsettled subagent
  * calls (pure, exported for the headless suite). The child's durable label
@@ -336,17 +539,6 @@ interface QueueFoldResult {
   /** Failed settlement summaries not yet notified (the caller notifies). */
   readonly failures: readonly string[];
 }
-/**
- * Build the queue-pane rows for one inbox batch, dropping background-subagent
- * settlement notices (the task browser is their surface) and reporting which
- * FAILED settlements should notify. Pure and injectable so the filter +
- * once-notify semantics are testable without the agent.
- * @param messages - one inbox batch (next-turn or next-step), in order.
- * @param mode - the delivery mode for surviving rows.
- * @param notified - the notify-once guard; failed notices already in it are
- *   skipped, and a newly-reported id is ADDED here so a re-render can never
- *   double-notify.
- */
 declare function foldQueueRows(messages: readonly QueueInboxMessage[], mode: 'followup' | 'steer', notified: Set<string>): QueueFoldResult;
 /**
  * Whether a shell command matches a destructive pattern. `rm` is treated
@@ -397,6 +589,11 @@ interface CompactionFold {
    * re-derived from the turn log (a stale end never clears a newer
    * compaction's state). */
   clear: boolean;
+  /** The compaction phase the event implies: compaction/start →
+   * 'summarizing', a MATCHED compaction/summary → 'applying'. Undefined
+   * when the event does not advance the phase (a stale summary, any
+   * compaction/end — the settle clears via {@link clear}). */
+  phase?: Exclude<CompactionPhase, 'idle'>;
   /** The settle notification for compaction/end, when one fires. */
   notify: {
     text: string;
@@ -413,6 +610,23 @@ declare function foldCompactionEvent(state: {
     error?: unknown;
   };
 }): CompactionFold;
+/** The minimal compaction-settle surface the runner passes in — STRUCTURAL
+ * on purpose: referencing the full {@link TuiApp} class from a public
+ * export would inline the whole surface (and its internal registry/
+ * presentation dependencies) into the published declaration bundle. The
+ * settle contract only needs the three phase/busy/working setters. */
+interface CompactionSettleSurface {
+  setCompactionPhase(phase: 'idle'): void;
+  setBusy(busy: boolean): void;
+  setWorking(busy: boolean): void;
+}
+/** The UI side effects of a MATCHED compaction settle: clear the phase,
+ * hand the working row back to the turn state, and re-measure the session
+ * surface so the footer context reflects the compacted log IMMEDIATELY —
+ * the next step/start or turn/end would otherwise delay the refresh.
+ * Exported as a seam so the settle contract is testable without a full
+ * runner driver (the firehose closure is not). */
+declare function settleCompactionSurface(app: CompactionSettleSurface, refreshStatus: () => void, busyNow: boolean): void;
 /** The busy flag after a turn-boundary event: a turn end must NOT clear
  * the busy state while a compaction is still in flight — an interrupted
  * turn can close (turn/end) before its compaction settles, and the
@@ -455,10 +669,20 @@ interface AgentComposition {
  * @param ctx - the runner context (services read through `ctx.get`).
  * @param selected - the mutable model selection every setup installs.
  * @param presetId - the requested preset, or `undefined` for the default.
+ * @param focusState - the shared Focus runtime state (STRUCTURAL on
+ *   purpose: the public declaration bundle must not inline src/focus.ts —
+ *   the parameter only ever carries the runner's FocusState object, so a
+ *   bare `{ enabled: boolean }` keeps the shipped .d.mts clean); when
+ *   provided, the setup ALSO installs the dynamic Focus system-prompt
+ *   section exactly once per composed agent (plan §9 — every composed
+ *   root TUI agent gets it; /focus toggles never re-register).
+ * @param diag - the diagnostics channel, when the caller has one.
  * @returns the id to record on the header (absent without a roster) and the setup callback.
  * @throws when the roster supplies no such preset.
  */
-declare function composeAgent(ctx: Context, selected: ModelSelectionRef, presetId?: string): Promise<AgentComposition>;
+declare function composeAgent(ctx: Context, selected: ModelSelectionRef, presetId?: string, focusState?: {
+  enabled: boolean;
+}, diag?: Diag): Promise<AgentComposition>;
 /**
  * The preset a persisted session actually runs, from its log (newest
  * selection winning), or undefined when persistence is absent, the session is
@@ -508,4 +732,4 @@ declare function recomposeBlank(ctx: Context, agent: {
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { AgentComposition, CompactionFold, Config, HOST_COMMAND_CATALOG, InitialCatalogResolution, LOCAL_COMMANDS, PendingSubagentCall, QueueFoldResult, QueueInboxMessage, QueueNoticeSource, RecomposableSession, RecomposeOutcome, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, SessionLockRefusedError, apply, busyAfterTurnBoundary, compactingFromLog, composeAgent, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, isPlainExitPrompt, isSubagentSettlementNotice, isUserQueueInput, matchPendingSubagentCall, name, recomposeBlank, recordedPreset, registerCredentialSurfaceRefresh, resolveInitialCatalog, resumeCommand, runningProfile, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure };
+export { AgentComposition, CompactionFold, CompactionSettleSurface, Config, HOST_COMMAND_CATALOG, InitialCatalogResolution, InterruptAgentLike, LOCAL_COMMANDS, PendingSubagentCall, QueueFoldResult, QueueInboxMessage, QueueNoticeSource, RecomposableSession, RecomposeOutcome, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, SessionLockRefusedError, ViewerOpenToken, apply, busyAfterTurnBoundary, commandRejectsImages, compactingFromLog, composeAgent, createViewerOpenToken, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, interruptAgent, isPlainExitPrompt, isSubagentSettlementNotice, isUserQueueInput, matchPendingSubagentCall, name, normalizeSkillInvocation, recomposeBlank, recordedPreset, registerCredentialSurfaceRefresh, resolveInitialCatalog, resumeCommand, runningProfile, settleCompactionSurface, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure, teardownViewerForSessionSwap, viewerActionCapability };

package/dist/index.mjs

@@ -1,3 +1,3 @@
 import "./startup.mjs";
-import { C as resumeCommand, D as subagentJobTranscriptId, E as shouldSteerOnEnter, O as subagentJobViewHint, S as resolveInitialCatalog, T as shouldConsumeAdvertisedMiss, _ as matchPendingSubagentCall, a as SessionLockRefusedError, b as recordedPreset, c as compactingFromLog, d as foldCompactionEvent, f as foldQueueRows, g as isUserQueueInput, h as isSubagentSettlementNotice, i as SESSIONLESS_COMMANDS, j as forkSeed, k as subagentNoticeIsFailure, l as composeAgent, m as isPlainExitPrompt, n as HOST_COMMAND_CATALOG, o as apply, p as inject, r as LOCAL_COMMANDS, s as busyAfterTurnBoundary, t as Config, u as dangerCommand, v as name, w as runningProfile, x as registerCredentialSurfaceRefresh, y as recomposeBlank } from "./src-ClAKiW0z.mjs";
-export { Config, HOST_COMMAND_CATALOG, LOCAL_COMMANDS, SESSIONLESS_COMMANDS, SessionLockRefusedError, apply, busyAfterTurnBoundary, compactingFromLog, composeAgent, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, isPlainExitPrompt, isSubagentSettlementNotice, isUserQueueInput, matchPendingSubagentCall, name, recomposeBlank, recordedPreset, registerCredentialSurfaceRefresh, resolveInitialCatalog, resumeCommand, runningProfile, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure };
+import { A as shouldConsumeAdvertisedMiss, C as recomposeBlank, D as resumeCommand, E as resolveInitialCatalog, F as teardownViewerForSessionSwap, I as viewerActionCapability, M as subagentJobTranscriptId, N as subagentJobViewHint, O as runningProfile, P as subagentNoticeIsFailure, R as forkSeed, S as normalizeSkillInvocation, T as registerCredentialSurfaceRefresh, _ as isPlainExitPrompt, a as SessionLockRefusedError, b as matchPendingSubagentCall, c as commandRejectsImages, d as createViewerOpenToken, f as dangerCommand, g as interruptAgent, h as inject, i as SESSIONLESS_COMMANDS, j as shouldSteerOnEnter, k as settleCompactionSurface, l as compactingFromLog, m as foldQueueRows, n as HOST_COMMAND_CATALOG, o as apply, p as foldCompactionEvent, r as LOCAL_COMMANDS, s as busyAfterTurnBoundary, t as Config, u as composeAgent, v as isSubagentSettlementNotice, w as recordedPreset, x as name, y as isUserQueueInput } from "./src-Txng8gIG.mjs";
+export { Config, HOST_COMMAND_CATALOG, LOCAL_COMMANDS, SESSIONLESS_COMMANDS, SessionLockRefusedError, apply, busyAfterTurnBoundary, commandRejectsImages, compactingFromLog, composeAgent, createViewerOpenToken, dangerCommand, foldCompactionEvent, foldQueueRows, forkSeed, inject, interruptAgent, isPlainExitPrompt, isSubagentSettlementNotice, isUserQueueInput, matchPendingSubagentCall, name, normalizeSkillInvocation, recomposeBlank, recordedPreset, registerCredentialSurfaceRefresh, resolveInitialCatalog, resumeCommand, runningProfile, settleCompactionSurface, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure, teardownViewerForSessionSwap, viewerActionCapability };

package/dist/{public-types-2omeXG8d.d.mts → public-types-CZz5_arj.d.mts}

@@ -35,6 +35,9 @@ interface TuiColorPalette {
   diffGutter: string;
   diffMeta: string;
   roleUser: string;
+  /** Optional user-bubble background (dsh-web `--dsw-specific-bubble`
+   * parity); absent = no bubble block. */
+  roleUserBg?: string;
   shellMode: string;
 }
 /** One autocomplete suggestion item (structural — the host maps it onto