@xiaoso/dsh-tool-plus 0.1.9 → 0.1.10-beta.1

package/lib/types/presets/conflicts.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 冲突不变式：一个 preset「接上了本插件的工具」当且仅当官方那 4 个工具行
+ * 处于**不存在**或 **`disabled: true`** 状态。
+ *
+ * 原因（这套设计的地基，别丢）：`@xiaoso/dsh-tool-plus` 作为包在**宿主面**
+ * 加载时，它自己的 profile 补丁已经禁用了这 4 行并插入**一行全局** `tool-plus`；
+ * 注册表按 scope 分层、就近优先，所以宿主面那一份已经服务所有会话。若某个
+ * preset 又在 **agent 面**挂一份同名工具行，就会用**第二个 `apply()` 影子实例**
+ * 盖掉健康的宿主实例，而那个实例的 settings 注入永不触发（cfg 退化成
+ * replace-mode 读取 —— 2026-08-25 hashline 事故的根因）。
+ *
+ * 与旧文本实现的唯一区别是**载体**：以前逐行读 `agent.cordis.yml` 的文本，
+ * 现在直接看宿主交给我们的行对象。判定规则一字不改：
+ * - 只认**顶层**行；group 里嵌套的同名行不碰；
+ * - `disabled` 严格等于布尔 `true` 才算已处理 —— 缺席、`false`、字符串、
+ *   `!!js` 表达式统统算冲突（`!!js` 在挂载时才求值，我们要的是无条件关闭，
+ *   所以和旧实现一样整值翻成 `true`）；
+ * - 输出恒为新数组，输入不变；结果与输入逐值相同时 `changes` 为空（调用方以
+ *   此判定"不写盘"）。
+ * @module @xiaoso/dsh-tool-plus/presets/conflicts
+ */
+import { type PresetRow } from './rows.ts';
+/** 官方 standard / ptc / cordis 会挂的 4 个工具行 id。 */
+export declare const PRESET_CONFLICT_IDS: readonly string[];
+/** 一次改写实际发生的一处改动。 */
+export interface PresetChange {
+    /** 行 id（顶层 `- id: <id>`）。 */
+    id: string;
+    /** `disabled` = 该行原本没有 `disabled` 键，现在补上；`flipped` = 既有值被翻成 `true`。 */
+    action: 'disabled' | 'flipped';
+}
+/** 只读判定：给设置页状态用。 */
+export interface PresetAnalysis {
+    /** 仍挂着冲突行的 id（缺 `disabled` 或值不是布尔 `true`），按 conflictIds 顺序。 */
+    conflicts: string[];
+    /** 无冲突且形状可识别。 */
+    clean: boolean;
+    /** `unrecognized` = 不是合法的顶层行列表，一律不处理也不改写。 */
+    shape: 'ok' | 'unrecognized';
+}
+/**
+ * 只读分析一份 `plugins` 值。
+ * @param plugins - 声明的子插件列表（来自宿主配置，形状未知）。
+ * @param conflictIds - 冲突行清单，默认 {@link PRESET_CONFLICT_IDS}。
+ * @returns 冲突清单、是否干净、形状是否可识别。
+ */
+export declare function analyzePlugins(plugins: unknown, conflictIds?: readonly string[]): PresetAnalysis;
+/** 改写结果：新列表 + 实际改动清单 + 改写后仍未解决的冲突（理论上为空）。 */
+export interface PresetConflictRewrite {
+    plugins: PresetRow[];
+    changes: PresetChange[];
+}
+/**
+ * 把那 4 个仍挂着的冲突行翻成 `disabled: true`（不改别的行、不删行）。
+ * @param plugins - 合法顶层行列表。
+ * @param conflictIds - 冲突行清单，默认 {@link PRESET_CONFLICT_IDS}。
+ * @returns 新列表与实际改动清单（无改动时 `changes` 为空且列表为原引用）。
+ */
+export declare function disableConflicts(plugins: readonly PresetRow[], conflictIds?: readonly string[]): PresetConflictRewrite;

package/lib/types/presets/delta.d.ts

@@ -1,16 +1,18 @@
 /**
- * 预设差异清单：只读地说清"用户这份和随包模板差在哪"。
+ * 差异清单：只读地说清"这份 preset 与另一份（通常是随包声明）差在哪"。
  *
  * 为什么需要它：`templateDiffers: boolean` 只能说"不一样"，而面板上紧挨着的
- * 是"工具冲突行都已禁用、无需调整"。两句都对，但读起来打架 —— 前者说的是
- * **你改过内容**，后者说的是**我们自己那 4 个冲突行**。把差异逐条列出来，
- * 面板才不需要用户自己猜"到底哪里不同、更新会不会动它"。
+ * 是"冲突行都已禁用、无需调整"。两句都对，读起来却打架 —— 前者说的是
+ * **内容被改过**，后者说的是**我们自己那 4 个冲突行**。把差异逐条列出来，
+ * 用户才不用猜"到底哪里不同、对齐会不会动它"。
  *
- * 契约：①比**展开到叶子的点号路径**（`config.thresholdRatio`，列表项带 `[i]`）——
- * 真实漂移常藏在嵌套键里，只比顶层键会得出"没有差异"的错误结论；②冲突行的
- * `disabled` 由 `conflicts` 负责，不在差异里重复报；③形状不可识别 → 空清单，
- * 绝不猜；④顺序＝用户这份的行序在前，模板独有的行补在后；⑤`total` 是全量，
- * `items` 可被 `limit` 截断（面板据此说"等 N 项"）。
+ * 契约（自旧文本实现原样继承，语义未变）：
+ * - 比**展开到叶子的点号路径**（`config.thresholdRatio`、`config.models[0].id`）——
+ *   真实漂移常藏在嵌套键里，只比顶层键会得出"没有差异"的错误结论；
+ * - 冲突行的 `disabled` 由 `conflicts` 负责，不在差异里重复报；
+ * - 形状不可识别 → 空清单，绝不猜；
+ * - 顺序 = 你这份的行序在前（含 group 内子行），对方独有的行补在后；
+ * - `total` 是全量，`items` 可被 `limit` 截断（面板据此说"等 N 项"）。
  * @module @xiaoso/dsh-tool-plus/presets/delta
  */
 /** 一条差异：整行只在一侧、某个叶子只在一侧、或同一个叶子两边值不同。 */
@@ -18,13 +20,16 @@ export type PresetDeltaKind = 'changed' | 'only-yours' | 'only-template' | 'row-
 /** 差异清单的一项。`path` 为空串表示整行层面的差异。 */
 export interface PresetDeltaItem {
     kind: PresetDeltaKind;
-    /** 顶层行的 id。 */
+    /**
+     * 行路径：顶层行的 id（`tool-web`），或 group 内子行（`delegation/tool-ralph`）。
+     * 用路径而不是裸 id，是因为嵌套行重名时裸 id 会指错行。
+     */
     row: string;
     /** 行内点号路径（如 `config.thresholdRatio`）；整行差异时为空串。 */
     path: string;
     /** 你这份里的值（`only-template` / `row-only-template` 时不带）。 */
     yours?: string;
-    /** 模板里的值（`only-yours` / `row-only-yours` 时不带）。 */
+    /** 对方的同名值（`only-yours` / `row-only-yours` 时不带）。 */
     template?: string;
 }
 /** 差异清单：`items` 已按 `limit` 截断，`total` 是全量条数。 */
@@ -32,21 +37,21 @@ export interface PresetDelta {
     items: PresetDeltaItem[];
     total: number;
     /**
-     * 全量口径的两个分组：`yoursCount` = 你自己加/改的（更新不覆盖，重置会覆盖），
-     * `behindCount` = 模板有而你没有的（模板已更新，重置可对齐）。
+     * 全量口径的两个分组：`yoursCount` = 你自己加/改的（对齐会覆盖它），
+     * `behindCount` = 对方有而你没有的（对方已更新，对齐可补上）。
      * 分组计数必须按**全量**算：`items` 被 `limit` 截断后数它会把"等 N 项"说错。
      */
     yoursCount: number;
     behindCount: number;
 }
 /**
- * 比较两份组合文件，列出差异（只读，不改任何字节）。
- * @param userText - 用户这份的 `agent.cordis.yml` 原文。
- * @param templateText - 随包模板的同一文件原文。
+ * 比较两份 `config.plugins`，列出差异（只读，不改任何值）。
+ * @param yours - 你这一侧的 plugins（形状未知）。
+ * @param theirs - 对方的 plugins（形状未知）。
  * @param options - `conflictIds`（默认 {@link PRESET_CONFLICT_IDS}）与 `limit`（默认 6）。
- * @returns 差异清单；两侧任一不可识别时为空清单。
+ * @returns 差异清单；两侧任一形状不可识别时为空清单。
  */
-export declare function presetDelta(userText: string, templateText: string, options?: {
+export declare function presetDelta(yours: unknown, theirs: unknown, options?: {
     conflictIds?: readonly string[];
     limit?: number;
 }): PresetDelta;

package/lib/types/presets/plan.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 动作判定：三个面板动作各自"要不要动手、动手算不算真改动"。**纯函数**。
+ *
+ * 这一层存在的理由：真正落盘的是宿主自己的 `ctx.configEditor.edit()`，它**每次
+ * 调用都会重写 profile 补丁文件**（哪怕内容一个字没变）。所以"是否值得写"必须
+ * 在调用它**之前**判定，否则面板每点一次都会白改一次 mtime、白触发一轮 HMR 重载。
+ * 判定所需的事实全部来自 {@link PresetFacts}，因此这里可以纯函数测试，不需要
+ * 真的 profile、也不需要 cordis。
+ *
+ * 三个动作的语义（自旧目录机制映射而来，见 CHANGELOG）：
+ * - `upgrade`（最小更新）：只把仍挂着的官方冲突行翻成 `disabled: true`。不改别的行，
+ *   不动显示元数据 —— 幂等，已干净时一个字节都不写。
+ * - `align`（对齐模板）：把生效的 plugins 整份换成所选模板声明的 plugins。
+ *   *对齐到自己的随包声明* = 撤销覆盖，等价于 `revert`，这里直接归约过去。
+ * - `revert`（恢复随包）：让宿主删掉 profile 补丁里那一行的 `config`，
+ *   于是这一行回落到随包声明。没有覆盖时是 no-op。
+ * @module @xiaoso/dsh-tool-plus/presets/plan
+ */
+import type { PresetChange } from './conflicts.ts';
+/** 面板可以请求的三个动作。 */
+export type PresetActionKind = 'upgrade' | 'align' | 'revert';
+/** 判定所需的全部事实。 */
+export interface PresetPlanInput {
+    action: PresetActionKind;
+    /** 这个 preset 是不是本插件声明的（只有 ours 允许 align / revert）。 */
+    ours: boolean;
+    /** 用户是否在 profile 层写过覆盖。 */
+    customized: boolean;
+    /** 生效的完整 config（宿主的 `entry.options.config`）；取不到时 undefined。 */
+    effective: Record<string, unknown> | undefined;
+    /** 随包声明那一层的完整 config（宿主的 `inherited`）。 */
+    inherited: Record<string, unknown> | undefined;
+    /** `align` 的目标模板 plugins。 */
+    templatePlugins?: unknown;
+    /** `align` 请求的模板 id（仅用于文案与校验）。 */
+    templateId?: string;
+}
+/** 判定结果。 */
+export type PresetPlan = {
+    kind: 'noop';
+    reason: string;
+} | {
+    kind: 'upgrade';
+    changes: PresetChange[];
+} | {
+    kind: 'align';
+} | {
+    kind: 'revert';
+};
+/**
+ * 判定一个动作该不该写、会改什么。
+ * @param input - 判定所需的事实。
+ * @returns 计划；`noop` 时调用方**不要**调用 `configEditor.edit`。
+ */
+export declare function planPresetAction(input: PresetPlanInput): PresetPlan;

package/lib/types/presets/rows.d.ts

@@ -0,0 +1,84 @@
+/**
+ * preset 组合的**行模型**：官方声明式 preset 的 `config.plugins` 就是一棵
+ * Cordis entry list，本模块是它唯一的读写口径。
+ *
+ * 为什么不再有 YAML 文本层：旧机制里预设是磁盘上的 `agent.cordis.yml`，我们
+ * 只能逐行做文本手术（保缩进、保注释、保 CRLF）。0.1.7 起预设是 profile 配置
+ * 里的一条声明，宿主给我们的**已经是解析好的对象树**（`configEditor` 的
+ * `inherited` / `override`，以及 `entry.options.config`），再走文本就是自找
+ * 麻烦：`!!js` 标记、块标量、引号风格全都不该由我们操心。
+ *
+ * 三条纪律：
+ * - **形状判定照抄官方**：顶层必须是行列表，且每一行是带非空字符串 `name`
+ *   的映射（官方 `entryListProblem` 同款）。不满足 → `undefined`，一律不处理。
+ * - **只认顶层行**：`tool-bash`/`tool-fs` 这类 id 只按顶层匹配；group 里嵌套的
+ *   同名行属于那个 group 的私有组成，绝不被外层动作波及。
+ * - **绝不原地改**：所有"改写"都返回新对象，输入保持可比较（宿主按深相等判定
+ *   是否落盘，原地改会让幂等判定失去意义）。
+ * @module @xiaoso/dsh-tool-plus/presets/rows
+ */
+/** 一行 Cordis 配置项的最小子集（其余键原样透传）。 */
+export interface PresetRow {
+    id?: unknown;
+    name?: unknown;
+    group?: unknown;
+    disabled?: unknown;
+    isolate?: unknown;
+    config?: unknown;
+    [key: string]: unknown;
+}
+/** 行 id 的取值（非空字符串才认，与官方对 `name` 的要求同款）。 */
+export declare function rowId(row: PresetRow): string | undefined;
+/** 行模块名（官方 entry-list 要求每行都有非空 `name`）。 */
+export declare function rowName(row: PresetRow): string | undefined;
+/** 这一行是不是 group 载体（group 的子行在 `config` 里）。 */
+export declare function isGroupRow(row: PresetRow): boolean;
+/**
+ * 判定一份 `plugins` 值是不是合法的顶层行列表。规则与官方
+ * `entryListProblem` 一致：必须是数组，每一项必须是带非空 `name` 的映射。
+ * @param value - 待判定的值（来自宿主配置或测试注入）。
+ * @returns 合法时为 true。
+ */
+export declare function isRowList(value: unknown): value is PresetRow[];
+/**
+ * 展平一棵行树（含 group 嵌套），键为 `父/子` 形式的路径。
+ *
+ * 路径是**给面板看的标识**，也用于我们自己的差异比较；官方
+ * `compositionInventory()` 回的行没有路径（它压平后只剩 entryId/moduleName），
+ * 所以需要分组结构时只能从声明本身取。
+ * @param rows - 顶层行列表。
+ * @param prefix - 递归时的父路径。
+ * @returns 路径 → 行。
+ */
+export declare function flattenRows(rows: readonly PresetRow[], prefix?: string): Map<string, PresetRow>;
+/** 一个叶子：行内点号路径 → 规范化后的值字符串。 */
+export interface RowLeaf {
+    /** 行内路径，如 `config.thresholdRatio` 或 `config.models[0].id`。 */
+    path: string;
+    /** 规范化值：标量走 `JSON.stringify`，所以 `true`/`"true"`/`1` 不会互相混淆。 */
+    value: string;
+}
+/**
+ * `!!js` 表达式标记：entry-list 方言把它解析成 `{ __jsExpr: <源码> }`（见
+ * `vendor/include/src/index.ts` 的 `JsExpr`）。它对我们是**标量**——一整段待求值的
+ * 源码，不是可以逐键比较的结构。漏了这一步会造出 `disabled.__jsExpr` 这种假叶子，
+ * 顺带让"冲突行的 disabled 归 conflicts 管"这条跳过规则失效。
+ * @param value - 待判定的值。
+ * @returns 是表达式标记时为 true。
+ */
+export declare function isJsExpr(value: unknown): value is {
+    __jsExpr: string;
+};
+/**
+ * 收集一行自己的叶子路径（不含 `id`，不含 group 的子行）。
+ *
+ * 用规范化 JSON 而不是 `String()`：Loader 对 `disabled` 的语义是
+ * "布尔取 Boolean(value)"，所以字符串 `"false"` 与布尔 `false` **语义相反**；
+ * 两者若都显示成 `false`，面板就会把一处真实差异藏起来。
+ * @param row - 目标行。
+ * @param base - 递归时的前缀。
+ * @returns 该行的叶子清单（顺序为键的声明顺序）。
+ */
+export declare function rowLeaves(row: PresetRow, base?: string): RowLeaf[];
+/** 规范化的深比较（两侧都是 YAML/JSON 值，无函数与原型差异）。 */
+export declare function sameValue(a: unknown, b: unknown): boolean;

package/lib/types/presets/status.d.ts

@@ -1,56 +1,65 @@
-import { type PresetDeps } from './paths.ts';
-import { type PresetDelta } from './delta.ts';
-/** 预设来源：我们随包的两份 / 用户自建 / 官方随附。 */
-export type PresetSource = 'ours' | 'user' | 'shipped';
 /**
- * roster 的一行（调用方从 `ctx.agentPresets.list()` 映射而来，字段名对齐
- * `dsh-agent-presets` 的 `AgentPreset`：`path` 是**组合文件**的绝对路径）。
+ * preset 状态：把宿主交给我们的事实折成设置页要的清单。同步、只读。
+ *
+ * 事实从哪来（0.1.7 起官方只提供这两处，`path` / `trust` 都已不存在）：
+ * - `ctx.configEditor.configuration()` —— 每个**可寻址**的 profile 行给
+ *   `{entry, inherited, override}`。`inherited` 是随包声明那一层（我们的
+ *   模板），`override` 是用户写进 profile 补丁那一层。bundle 补丁 insert 的
+ *   `preset-*` 行也是根 include 的子行，所以这里拿得到。
+ * - `ctx.agentPresets.list()` —— 名册身份与激活诊断（`broken`），**没有**
+ *   `path`，也**没有** `trust`。
+ *
+ * 三种来源的旧口径已失效，现在的区分只剩"是不是本插件声明的"：
+ * - `ours`：id 在 {@link BUNDLED_PRESET_IDS} 里 → 三个动作齐全；
+ * - `other`：别人的声明（官方随附，或用户装的别的 bundle）→ 只给"最小更新"，
+ *   因为我们只该修冲突行，不该替别人重写整份内容。
+ * @module @xiaoso/dsh-tool-plus/presets/status
  */
-export interface PresetRosterEntry {
-    id: string;
-    trust: 'system' | 'user';
-    path: string;
-    name?: string;
-    description?: string;
-    broken?: string;
-}
-/** 一个预设的设置页状态。 */
-export interface PresetStatus {
+import { type PresetStatusListValue, type PresetStatusValue } from '../tools/shared/browser-rpc-channel.ts';
+/**
+ * 一个 preset 的原始事实（宿主层收集，本模块纯消费）。
+ *
+ * `inherited` / `override` 是**完整 config 对象**（`{id,name,description,order,plugins}`），
+ * 不是 plugins 列表 —— 因为 profile 补丁按行 id 覆盖时替换的是**整份 `config`**，
+ * 判断"改没改过"必须看整份，不能只看 plugins。
+ */
+export interface PresetFacts {
+    /** 预设身份（`config.id`）。 */
     id: string;
+    /** profile 补丁里那一行的 id（`preset-<id>`）；本 profile 没有这一行时为 undefined。 */
+    entryId?: string;
     name?: string;
     description?: string;
-    source: PresetSource;
-    /** 组合文件绝对路径（`agent.cordis.yml`）。 */
-    path: string;
-    /** 仍挂着的官方冲突行（空 = 本插件的工具已生效）。 */
-    conflicts: string[];
-    /** 无冲突且形状可识别。 */
-    clean: boolean;
-    /** 组合文件**可读但**不成顶层行列表 → 一律不处理（内容问题，§5.5）。 */
-    unrecognized: boolean;
-    /** roster 报告的不可挂载原因，原样带出。 */
+    isDefault: boolean;
+    /** 宿主报告的不可挂载原因（行名解析不到、缺服务…），原样带出。 */
     broken?: string;
-    /**
-     * 用户根（`<dshHome>/.agent-presets/<id>`）里有这个预设的副本。
-     * 设置页对我们随包的两份据此显示"已安装 / 未安装"；官方随附的预设不在用户
-     * 根，故恒为 false。
-     */
-    installed: boolean;
-    /** 包内存在这个 id 的模板（只有我们随包的两份才有）。 */
-    templatePresent: boolean;
-    /** 已安装且与模板逐字节不同 → 本地有改动（重置会覆盖它）。 */
-    templateDiffers: boolean;
-    /**
-     * 与模板**具体**差在哪些键（只读列出；`templateDiffers` 只说明"有差异"，
-     * 面板需要能说清"差在哪"，否则和"工具行无需调整"并列时会自相矛盾）。
-     * 无模板或不可比较时为 undefined。
-     */
-    templateDelta?: PresetDelta;
+    /** 生效的完整 config（宿主的 `entry.options.config`）；取不到时为 undefined。 */
+    effective?: Record<string, unknown>;
+    /** 随包声明那一层的 config（`configEditor` 的 `inherited`）；取不到时为 undefined。 */
+    inherited?: Record<string, unknown>;
+    /** 用户在 profile 层写的 config（`configEditor` 的 `override`）；空对象 = 没有覆盖。 */
+    override?: Record<string, unknown>;
+    /** 这个 preset 是不是本插件声明的（id ∈ {@link BUNDLED_PRESET_IDS}）。 */
+    ours: boolean;
 }
 /**
- * 列出每个 roster 行的状态（顺序与入参一致）。
- * @param roster - 调用方映射好的预设清单（`path` = 组合文件路径）。
- * @param deps - 路径注入（fs 层测试用）。
- * @returns 逐行的设置页状态。
+ * 把一个 preset 折成面板状态。
+ * @param facts - 宿主收集的原始事实。
+ * @param templateIds - 随包声明的模板清单（用于"与随包声明是否一致"）。
+ * @returns 面板状态行。
+ */
+export declare function toPresetStatus(facts: PresetFacts, templateIds: readonly string[]): PresetStatusValue;
+/**
+ * 列出每个事实的状态，并给出模板清单。
+ * @param facts - 宿主收集的原始事实（顺序即面板顺序）。
+ * @param writable - 本部署有没有可编辑的 profile（`configEditor` 是否在场）。
+ * @returns `presets/status` 的完整返回值。
+ */
+export declare function listPresetStatuses(facts: readonly PresetFacts[], writable: boolean): PresetStatusListValue;
+/**
+ * 取某个模板声明的 plugins（面板"对比 / 对齐"的右侧）。
+ * @param facts - 同一个事实集合。
+ * @param templateId - 模板 id（本插件声明的某个 preset）。
+ * @returns 该模板的 plugins；不是我们的模板时 undefined。
  */
-export declare function listPresetStatuses(roster: readonly PresetRosterEntry[], deps?: PresetDeps): PresetStatus[];
+export declare function templatePlugins(facts: readonly PresetFacts[], templateId: string): unknown;

package/lib/types/tools/bash/background.d.ts

@@ -2,11 +2,13 @@
  * Background-job adaptation for the `ctx.jobs` seam: one managed job runs its
  * command on its OWN `:async:` Shell (never the session's persistent shell),
  * so background work never blocks the foreground session. The registry owns
- * identity, lifecycle state, and completion notices (`dsh-tool-jobs` injects
- * them); this module owns the execution resources and their hooks.
+ * identity, lifecycle state, the output ring, and completion notices
+ * (`dsh-tool-jobs` injects them); this module owns the execution resources,
+ * streams the run into that ring, and appends the plugin's completion message
+ * once the run ends.
  * @module @xiaoso/dsh-tool-plus/background
  */
-import type { JobHooks } from '@deepseek-ai/dsh-jobs';
+import type { JobHandle, JobHooks } from '@deepseek-ai/dsh-jobs';
 import type { BashForegroundOutput, ResolvedConfig } from './types.ts';
 export interface ManagedBashJob {
     /** Hooks handed to `ctx.jobs.start`'s `run()`. */
@@ -29,11 +31,24 @@ export interface StartBashJobOptions {
     /** Command-scoped environment (already merged with dshEnv). */
     env: Record<string, string> | undefined;
     config: ResolvedConfig;
+    /**
+     * The registry's producer face, when this run is a registered job: every
+     * streamed chunk lands in the job's output ring, and so does the settled
+     * completion message. Absent for a run no registry owns (unit callers).
+     */
+    job?: JobHandle;
+    /**
+     * Builds the settled completion message from the bounded preview and the
+     * run's spill file (the plugin's `outputTruncate` policy). Absent keeps the
+     * preview verbatim.
+     */
+    formatCompletion?: (previewText: string, spillPath: string | undefined) => string;
 }
 /**
  * Start one managed background bash job. The producer owns a per-job
- * `AbortController` (cancellation kills only this job's shell), a bounded
- * preview tail, and a consuming delta cursor for `readOutput`.
+ * `AbortController` (cancellation kills only this job's shell) and a bounded
+ * preview tail; the registry owns the model's consuming cursor over the ring
+ * this job writes to.
  * @param options - job identity and execution parameters.
  * @returns the registry hooks plus the tool-result completion promise.
  */

package/lib/types/tools/bash/streaming-output.d.ts

@@ -17,8 +17,10 @@ export declare class OutputSink extends VerbatimOutputSink {
 }
 /**
  * Composition wrapper over the verbatim {@link TailBuffer}, adding the DSH
- * `reset()` increment. The verbatim class keeps its state in private fields,
- * so reset is modeled as a fresh window with the same budget.
+ * `reset()` increment: the consuming-read cursor reset the bash background
+ * producer used while `JobHooks.readOutput` existed. 0.1.7 moves the model's
+ * cursor onto the job registry's output ring, so the increment is no longer
+ * part of that path; the preview buffer still offers it.
  */
 export declare class TailBuffer {
     #private;