berry-agent 0.1.0-alpha.1

package/dist/channels/tui/backend/ansi-rows.js

@@ -0,0 +1,211 @@
+/**
+ * 主屏 inline 形态 ANSI 编舞基件（07 §4.1「屏幕模型双形态」主屏条——批 10e）。
+ *
+ * 主屏物理形态：DECSTBM 滚动区承载正文（区底写满自动滚——滚出视口整行交
+ * 终端原生 scrollback），固定区（输入框 + 状态行）钉屏底区外、绝对位可知。
+ * 本件提供四组原语：
+ * - 网格行 → ANSI 序列化（cell 样式 + 字素——与 diff 件行写出同语义：续格
+ *   跳过、语义空格字面、行尾不填充）；
+ * - 网格行 → 带样式行（StyleRun 段族——批 10f-4 件 8 回看器 cell 写出形的
+ *   数据源；带样式行 → ANSI 序列化同件在位，主屏直写与回看器零第二渲染器）；
+ * - 定位序列（绝对 CUP / 相对 CUU·CUD / CR / EL）与光标保存恢复；
+ * - 行级差分（固定区重画——变行重写、未变行零写出，行粒度复用 cellEquals）。
+ */
+import { cellEquals, EMPTY_STYLE, styleEquals } from '../../engine/index.js';
+/** ESC 前缀 */
+const ESC = '\x1b';
+/** 缺省样式判据：styleEquals 对 EMPTY_STYLE 单源（CellStyle 增字段自动同步——
+ * 勿手工罗列字段判缺省，10f-4 核验轮勘正） */
+function isDefaultStyle(style) {
+    return styleEquals(style, EMPTY_STYLE);
+}
+/** SGR 全复位 */
+export const SGR_RESET = `${ESC}[0m`;
+/** EL 0：自光标至行尾 */
+export const EL_TO_EOL = `${ESC}[K`;
+/** 回行首（列 0——不滚行） */
+export const CR = '\r';
+/** 换行（滚动区内：区底自动滚、区外/中部只下移） */
+export const LF = '\n';
+/** 光标保存 / 恢复（DECSC/DECRC——编舞对（擦写远端区）后还原位） */
+export const SAVE_CURSOR = `${ESC}7`;
+export const RESTORE_CURSOR = `${ESC}8`;
+/** 清全屏 + 光标归位（repaint 路） */
+export const CLEAR_SCREEN = `${ESC}[2J${ESC}[H`;
+/** 设滚动区 DECSTBM（1 基行号——底部固定区留区外） */
+export function setScrollRegion(bottomRow1Based) {
+    return `${ESC}[1;${bottomRow1Based}r`;
+}
+/** 绝对定位（0 基入参——固定区专用：区外钉屏底、绝对位可知） */
+export function cup(row, col) {
+    return `${ESC}[${row + 1};${col + 1}H`;
+}
+/** 相对上移 n 行（CUU——滚动区内槽位重画定位；边缘安全不滚） */
+export function cuu(n) {
+    return n > 0 ? `${ESC}[${n}A` : '';
+}
+/** 相对下移 n 行（CUD——边缘安全不滚） */
+export function cud(n) {
+    return n > 0 ? `${ESC}[${n}B` : '';
+}
+/** 样式 → SGR（与 diff 件 buildSgr 同语义：属性位 + 16 色前景背景全量形；简行块直拼消费） */
+export function buildSgr(style) {
+    const params = [];
+    if (style.bold)
+        params.push('1');
+    if (style.dim)
+        params.push('2');
+    if (style.italic)
+        params.push('3');
+    if (style.underline)
+        params.push('4');
+    if (style.inverse)
+        params.push('7');
+    if (style.fg !== undefined)
+        params.push(String(style.fg < 8 ? 30 + style.fg : 82 + style.fg));
+    if (style.bg !== undefined)
+        params.push(String(style.bg < 8 ? 40 + style.bg : 92 + style.bg));
+    return params.length > 0 ? `${ESC}[${params.join(';')}m` : '';
+}
+/**
+ * 网格行 → ANSI 文本（无内容返回空串——调用方据此跳过写出）。
+ * 行尾变空白不产 EL（直写正文行是追加语义、行尾从无旧残留——EL 归擦区编舞）。
+ */
+export function gridRowToAnsi(grid, row) {
+    // 内容末列 = 最右非空格格（续格属首格字素占位、算内容延伸）
+    let last = -1;
+    for (let col = grid.columns - 1; col >= 0; col--) {
+        if (!cellEquals(grid.getCell(row, col), null)) {
+            last = col;
+            break;
+        }
+    }
+    if (last < 0)
+        return '';
+    let out = '';
+    // 当前样式序列（'' = 裸文本态；同样式零冗余、变化点复位再设——与 diff 件同纪律）
+    let currentSgr = '';
+    for (let col = 0; col <= last; col++) {
+        const cell = grid.getCell(row, col);
+        if (cell !== null && cell.width === 0)
+            continue; // 续格跳过
+        if (cell === null) {
+            out += ' '; // 语义空格（行中内容洞）字面写
+            continue;
+        }
+        const sgr = buildSgr(cell.style);
+        if (sgr !== currentSgr) {
+            out += (currentSgr !== '' ? SGR_RESET : '') + sgr;
+            currentSgr = sgr;
+        }
+        out += cell.grapheme;
+    }
+    if (currentSgr !== '')
+        out += SGR_RESET; // 行尾归零——不染后续写出
+    return out;
+}
+/**
+ * 网格行 → 带样式行（批 10f-4 件 8——回看器 cell 写出形的数据源）。
+ * 行走序与 gridRowToAnsi 同构（末列内容界 + 续格跳过 + 空洞空格），相邻同样式
+ * 格合并为单段；缺省样式段不产段（与空隙同形——序列化零冗余的基础）。
+ * 无内容行返回 null（调用方按需补空行——与 gridRowToAnsi 空串约定同构）。
+ */
+export function gridRowToStyled(grid, row) {
+    // 内容末列 = 最右非空格格（续格属首格字素占位、算内容延伸）
+    let last = -1;
+    for (let col = grid.columns - 1; col >= 0; col--) {
+        if (!cellEquals(grid.getCell(row, col), null)) {
+            last = col;
+            break;
+        }
+    }
+    if (last < 0)
+        return null;
+    let plain = '';
+    const runs = [];
+    for (let col = 0; col <= last; col++) {
+        const cell = grid.getCell(row, col);
+        if (cell !== null && cell.width === 0)
+            continue; // 续格跳过（首格已携整字素）
+        const grapheme = cell === null ? ' ' : cell.grapheme; // 语义空格（行中内容洞）
+        const style = cell === null ? EMPTY_STYLE : cell.style;
+        const start = plain.length;
+        plain += grapheme; // 全字素入 plain（缺省样式字素是空隙文本——不丢字）
+        if (isDefaultStyle(style))
+            continue; // 缺省段不产段（gap 即裸文本）
+        // 同样式紧邻续段合并（段端点连续才并——中间有缺省格即断开）
+        const prev = runs[runs.length - 1];
+        if (prev !== undefined && styleEquals(prev.style, style) && prev.end === start) {
+            runs[runs.length - 1] = { start: prev.start, end: start + grapheme.length, style };
+        }
+        else {
+            runs.push({ start, end: start + grapheme.length, style });
+        }
+    }
+    return { plain, runs };
+}
+/**
+ * 带样式行 → ANSI 串（主屏直写形——与 gridRowToAnsi 同语义的行序列化：
+ * 样式变化点复位再设、同样式零冗余、行尾归零不染后续写出）。
+ * renderBlockLines 经本函数从带样式行导出 ANSI 形——两形零第二渲染器。
+ */
+export function styledLineToAnsi(line) {
+    const { plain, runs } = line;
+    if (runs.length === 0)
+        return plain;
+    let out = '';
+    let currentSgr = '';
+    let pos = 0;
+    for (const run of runs) {
+        if (run.start > pos) {
+            // 段前空隙：在身样式先归零再写裸文本
+            if (currentSgr !== '') {
+                out += SGR_RESET;
+                currentSgr = '';
+            }
+            out += plain.slice(pos, run.start);
+        }
+        const sgr = buildSgr(run.style);
+        if (sgr !== currentSgr) {
+            out += (currentSgr !== '' ? SGR_RESET : '') + sgr;
+            currentSgr = sgr;
+        }
+        out += plain.slice(run.start, run.end);
+        pos = run.end;
+    }
+    if (pos < plain.length) {
+        // 段尾空隙：归零后写裸文本
+        if (currentSgr !== '') {
+            out += SGR_RESET;
+            currentSgr = '';
+        }
+        out += plain.slice(pos);
+    }
+    if (currentSgr !== '')
+        out += SGR_RESET;
+    return out;
+}
+/**
+ * 固定区行级差分（行粒度——变行整行重写、未变行零写出）。
+ * 返回 ANSI 串（含定位与行尾 EL——擦除只走 EL 禁空格填充）；行位以
+ * baseRow 屏偏移绝对定位（固定区钉屏底、区外位可知）。
+ */
+export function renderFixedRegionDiff(from, to, baseRow) {
+    let out = '';
+    for (let row = 0; row < to.rows; row++) {
+        if (from !== null && row < from.rows && gridRowEquals(from, to, row))
+            continue; // 未变行零写出
+        const text = gridRowToAnsi(to, row);
+        // 定位行首 → 复位 →（有内容写内容）→ 无条件 EL（行尾残留擦除——与 diff 件同律）
+        out += cup(baseRow + row, 0) + SGR_RESET + (text !== '' ? text + SGR_RESET : '') + EL_TO_EOL;
+    }
+    return out;
+}
+/** 行相等判定（逐格 cellEquals 直比） */
+function gridRowEquals(a, b, row) {
+    for (let col = 0; col < b.columns; col++) {
+        if (!cellEquals(a.getCell(row, col), b.getCell(row, col)))
+            return false;
+    }
+    return true;
+}

package/dist/channels/tui/backend/main-screen.js

@@ -0,0 +1,207 @@
+/**
+ * 主屏 inline 形态编舞件（07 §4.1「屏幕模型双形态」主屏条——批 10e）。
+ *
+ * 物理形态（与副屏全屏网格分立、共用 cell/diff/width 基座——07 篇定形）：
+ * - **DECSTBM 滚动区**承载正文（顶行到固定区上方）：区底写满自动滚、
+ *   滚出视口整行交终端原生 scrollback（历史真相在 durable 事件日志，行集
+ *   是帽内最近段的内存上限语义）；
+ * - **固定区钉屏底**（区外行不被滚动卷入、绝对位可知）：输入框 + 状态行，
+ *   行级差分重画（变行整行重写、未变行零写出——擦除只走 EL 禁空格填充）；
+ * - **正文块直写**：块 → 行序列化 → 追加写（追加不回改——直播路「消息事件
+ *   唯一渲染源」的物理形）；流式槽原位换装是视口内唯一差分。序列化单源走
+ *   renderBlockLines（批 10f-4 提取——件 8 回看器全量档复用同一渲染管线，
+ *   零第二渲染器）。
+ *
+ * 编舞状态模型：**绝对行跟踪**。件内维护光标绝对行 cursorRow 与 durable
+ * 末行 durableEndRow（= 下一条追加的落笔行 = 流式槽首行），每次写行经
+ * writeLine 单点维护（区底 LF 触滚钉区底——滚动量不外显）；present 尾光标
+ * 归固定区末行行首（呈现不变式——编舞内相对定位全由此出发；固定区自身用
+ * 绝对 CUP，钉屏底位可知）。
+ *
+ * v1 已知边界：流式槽 partial 回缩（新行数少于旧）按余行 EL 清——inline
+ * 终端无删行机制；固定区高度变化时光标账按区底钳制（内容可能被固定区
+ * 覆盖——装配宜随高度变化触发 repaint 重建）。
+ */
+import { CellGrid } from '../../engine/index.js';
+import { CLEAR_SCREEN, CR, cud, cuu, EL_TO_EOL, LF, renderFixedRegionDiff, setScrollRegion, cup } from './ansi-rows.js';
+import { renderBlockLines } from './transcript.js';
+/** 缺省几何（真值以 io.size() 为准——resize 路装配调 handleResize） */
+const DEFAULT_COLUMNS = 80;
+const DEFAULT_ROWS = 24;
+/**
+ * 主屏编舞：正文直写 + 槽换装 + 固定区差分。无自驱时钟（请求合并归装配），
+ * 所有公开方法同步产写出（测试经 MemoryTerminalIO 收帧断言）。
+ */
+export class MainScreen {
+    io;
+    columns = DEFAULT_COLUMNS;
+    rows = DEFAULT_ROWS;
+    fixedHeight;
+    /** 已直写 durable 块数（增量追加起点——repaint 归零全量重写） */
+    writtenBlocks = 0;
+    /** 光标绝对行（0 基——写行/定位单点维护） */
+    cursorRow = 0;
+    /** durable 末行（追加落笔行 = 槽首行；滚动时钉区底） */
+    durableEndRow = 0;
+    /** 当前槽直写行数（余行清除上界依据） */
+    slotLineCount = 0;
+    /** 固定区网格（装配画好交入——null = 固定区未装配只归位光标） */
+    fixedGrid = null;
+    /** 固定区上次呈现网格（行级差分基准；null = 全量重画） */
+    prevFixed = null;
+    constructor(io, options) {
+        this.io = io;
+        this.fixedHeight = options.fixedHeight;
+        const size = io.size();
+        this.columns = size.columns;
+        this.rows = size.rows;
+    }
+    /** 几何观测（装配层 resize 编舞消费） */
+    get geometry() {
+        return { columns: this.columns, rows: this.rows };
+    }
+    /** 启动编舞：清屏 + 滚动区确立 + 光标归位（呈现不变式自洽） */
+    start() {
+        this.io.write(CLEAR_SCREEN);
+        this.applyScrollRegion();
+    }
+    /**
+     * 增量呈现（追加块直写 → 槽换装 → 余行清除 → 固定区差分）。
+     * 前置：光标在固定区末行行首（start / setFixed / 上次 present 归位）。
+     */
+    present(blocks) {
+        // 末块为 streaming 时即流式槽（const 绑定经 kind 判别收窄）
+        const last = blocks.length > 0 ? blocks[blocks.length - 1] : null;
+        const slot = last !== null && last.kind === 'streaming' ? last : null;
+        const durableCount = slot === null ? blocks.length : blocks.length - 1;
+        // 余行清除上界：上次呈现的槽末行（= durable 末 + 槽行数 - 1——本帧前的账）
+        const prevBottomRow = Math.min(this.rows - this.fixedHeight - 1, this.durableEndRow + this.slotLineCount - 1);
+        // 光标归 durable 末（B/C 共同起点——无新增块时 C 段也从这里起笔）
+        this.gotoRow(this.durableEndRow);
+        // B. 追加块直写（每行 CR 起笔 + LF 推进，区底触滚交 scrollback）
+        if (durableCount > this.writtenBlocks) {
+            for (let i = this.writtenBlocks; i < durableCount; i++) {
+                this.writeBlockLines(blocks[i]);
+            }
+            this.writtenBlocks = durableCount;
+            this.durableEndRow = this.cursorRow;
+        }
+        // C. 槽换装（光标已在槽首 = durable 末；partial 是完整快照——逐行整写）
+        const slotLines = slot === null ? [] : this.renderSlotLines(slot);
+        for (const line of slotLines) {
+            this.writeLine(line);
+        }
+        // D. 余行清除（新槽末到上次槽末之间的 stale 行——EL 擦除禁空格填充）
+        const fixedTop = this.rows - this.fixedHeight;
+        const clearEnd = Math.min(fixedTop - 1, prevBottomRow);
+        for (let row = this.cursorRow; row <= clearEnd; row++) {
+            this.io.write((row > this.cursorRow ? cud(1) : '') + CR + EL_TO_EOL);
+        }
+        // E. 固定区差分重画 + 光标归位（呈现不变式）
+        this.redrawFixed();
+        this.slotLineCount = slotLines.length;
+    }
+    /**
+     * 瞬时行直写（非聚焦摘要行 / notify 通知行——不进行集不记 writtenBlocks，
+     * repaint 不重建）。编舞同追加块：归 durable 末 → 写行 → 余行清除 → 归位。
+     * 行内容由调用方（TuiBackend）序列化——本件纯编舞不做着色决策。
+     */
+    appendTransient(lines) {
+        if (lines.length === 0)
+            return;
+        this.gotoRow(this.durableEndRow);
+        for (const line of lines) {
+            this.writeLine(line);
+        }
+        this.durableEndRow = this.cursorRow;
+        const fixedTop = this.rows - this.fixedHeight;
+        const clearEnd = Math.min(fixedTop - 1, this.durableEndRow + this.slotLineCount - 1);
+        for (let row = this.cursorRow; row <= clearEnd; row++) {
+            this.io.write((row > this.cursorRow ? cud(1) : '') + CR + EL_TO_EOL);
+        }
+        this.redrawFixed();
+    }
+    /** 固定区网格更新（装配直呼——行级差分；几何变化时滚动区重设 + 差分基准失效） */
+    setFixed(grid) {
+        if (grid.rows !== this.fixedHeight) {
+            this.fixedHeight = grid.rows;
+            this.applyScrollRegion();
+            this.prevFixed = null; // 高度变化——差分基准失效全量重画；durable 末行按区底钳
+            this.durableEndRow = Math.min(this.durableEndRow, this.rows - this.fixedHeight - 1);
+            this.slotLineCount = 0;
+        }
+        this.fixedGrid = grid;
+        this.redrawFixed();
+    }
+    /** repaint（焦点切换）：清屏 + 行集全量重写（投影即真相——scrollback 旧内容不参与） */
+    repaint(blocks) {
+        this.writtenBlocks = 0;
+        this.slotLineCount = 0;
+        this.durableEndRow = 0;
+        this.io.write(CLEAR_SCREEN);
+        this.applyScrollRegion();
+        this.present(blocks);
+    }
+    /** resize 编舞：几何重取 + 滚动区重设 + 全量重画（弃旧换新——宽字符 reflow 必失真） */
+    handleResize(blocks) {
+        const size = this.io.size();
+        this.columns = size.columns;
+        this.rows = size.rows;
+        this.repaint(blocks);
+    }
+    /* ---------------- 内部编舞 ---------------- */
+    /** 滚动区确立/重设（DECSTBM 规范行为是光标归 home——随后显式归位呈现不变式位） */
+    applyScrollRegion() {
+        const bottom = Math.max(1, this.rows - this.fixedHeight);
+        this.io.write(setScrollRegion(bottom));
+        this.io.write(cup(this.rows - 1, 0));
+        this.cursorRow = this.rows - 1;
+    }
+    /** 写一行（CR 起笔 + LF 推进）并维护 cursorRow；区底 LF 触滚——内容整体上移一格、durableEndRow 同步减一（账不漂移） */
+    writeLine(text) {
+        this.io.write(CR + text + LF);
+        const regionBottom = this.rows - this.fixedHeight - 1;
+        if (this.cursorRow < regionBottom)
+            this.cursorRow++;
+        else if (this.durableEndRow > 0)
+            this.durableEndRow--; // 触滚：已写内容上移（B 段随后整账重赋、槽写路保持真值）
+    }
+    /** 光标归行（present 入口光标在固定区末行——CUU 相对定位即可达全屏任意行） */
+    gotoRow(row) {
+        const distance = this.cursorRow - row;
+        if (distance > 0)
+            this.io.write(cuu(distance));
+        else if (distance < 0)
+            this.io.write(cud(-distance));
+        this.cursorRow = row;
+    }
+    /** 固定区差分重画 + 光标落位（编辑光标外显的物理位） */
+    redrawFixed() {
+        if (this.fixedGrid !== null) {
+            const baseRow = this.rows - this.fixedGrid.rows;
+            this.io.write(renderFixedRegionDiff(this.prevFixed, this.fixedGrid, baseRow));
+            this.prevFixed = this.fixedGrid;
+            // 光标声明位落位（EditorView 编辑位经 setCursor 声明）——绝对 CUP 且
+            // 行账同步（gotoRow 相对定位数学依赖 cursorRow 真值）；无声明回退
+            // 屏底行首（呈现不变式原样）
+            const declared = this.fixedGrid.cursor;
+            if (declared !== null) {
+                const row = Math.min(baseRow + declared.row, this.rows - 1); // 越界声明防御钳屏底
+                this.io.write(cup(row, declared.col));
+                this.cursorRow = row;
+                return;
+            }
+        }
+        this.io.write(cup(this.rows - 1, 0));
+        this.cursorRow = this.rows - 1;
+    }
+    /** 块 → 行序列化直写（序列化单源 renderBlockLines——件 8 回看器复用同一管线，批 10f-4） */
+    writeBlockLines(block) {
+        for (const line of renderBlockLines(block, this.columns))
+            this.writeLine(line);
+    }
+    /** 流式槽行（纯文本直推——性能：不走网格不走样式；序列化同源 renderBlockLines） */
+    renderSlotLines(slot) {
+        return renderBlockLines(slot, this.columns);
+    }
+}

package/dist/channels/tui/backend/osc.js

@@ -0,0 +1,91 @@
+/** 保活重发周期（ms——pi-tui TERMINAL_PROGRESS_KEEPALIVE_MS 实证值） */
+export const OSC_PROGRESS_KEEPALIVE_MS = 1000;
+/** OSC 9;4 忙态序列（indeterminate progress——state 3） */
+const PROGRESS_ACTIVE_SEQUENCE = '\x1b]9;4;3\x07';
+/** OSC 9;4 清零序列（state 0） */
+const PROGRESS_CLEAR_SEQUENCE = '\x1b]9;4;0\x07';
+/**
+ * OSC 52 选区复制序列（07 §4.1 呈现面件 8 细则——BEL 终界）：
+ * `\x1b]52;c;<base64>\x07`，`c` = 系统剪贴板主位。终端支持不可探测（无标准
+ * 应答——kitty/Alacritty/wezterm/foot 支持、iTerm2 默认禁需用户开、tmux 需
+ * set-clipboard on、xterm 兼容族受 allowWindowOps 门控）——尽力写出无反馈，
+ * 不构成故障面。写出柄归装配层注入（onCopy），本函数只铸字节。
+ */
+export function buildOsc52Copy(text) {
+    return `\x1b]52;c;${Buffer.from(text, 'utf8').toString('base64')}\x07`;
+}
+/**
+ * 终端外显件：OSC title + 进度态两写点的最小自持件。
+ * 忙态期间保活自重排（触发即清位再续针——armTick 同形）；restore/停针后
+ * 句柄位归 null，重复停针是 no-op。
+ */
+export class OscDisplay {
+    /** title 值缓存（null = 未写过——同值不重写判据位） */
+    lastTitle = null;
+    /** 保活在飞句柄（null = 无在飞——名册语义判据位） */
+    keepaliveHandle = null;
+    io;
+    baseline;
+    schedule;
+    cancel;
+    constructor(io, options) {
+        this.io = io;
+        this.baseline = options.baseline;
+        this.schedule = options.schedule ?? null;
+        // 取消缺省兜底 setTimeout 句柄族（与 TuiBackend cancelFn 缺省同形）
+        this.cancel = options.cancel ?? ((handle) => clearTimeout(handle));
+    }
+    /** 在飞保活句柄现值（null = 无在飞——名册摘除/测试断言位） */
+    get activeKeepalive() {
+        return this.keepaliveHandle;
+    }
+    /** 标题写出（OSC 0;… BEL——值缓存去重：同值不重写字节） */
+    setTitle(title) {
+        if (title === this.lastTitle)
+            return; // 去重律——同值零字节
+        this.lastTitle = title;
+        this.io.write(`\x1b]0;${title}\x07`);
+    }
+    /**
+     * 进度态写出（OSC 9;4）：
+     * - true = 写忙态序列 + 起 1s 保活周期重发（已在飞不重复起针——重发维持
+     *   单链不叠针）；同值重复调用仍重写忙态序列（去重不适用于 progress）；
+     * - false = 写清零序列 + 停保活 timer。
+     */
+    setProgress(active) {
+        if (active) {
+            this.io.write(PROGRESS_ACTIVE_SEQUENCE);
+            this.armKeepalive();
+        }
+        else {
+            this.stopKeepalive();
+            this.io.write(PROGRESS_CLEAR_SEQUENCE);
+        }
+    }
+    /**
+     * 退出复原两写点齐（07 §4.1 件 7 条款）：title 复原基线（经值缓存——
+     * 已在基线则零字节）+ 进度清零（无条件写——终态收口，含停保活）。
+     */
+    restore() {
+        this.stopKeepalive();
+        this.setTitle(this.baseline);
+        this.io.write(PROGRESS_CLEAR_SEQUENCE);
+    }
+    /** 停保活定时器（名册语义：句柄非空才取消、停后清位——重复停针 no-op） */
+    stopKeepalive() {
+        if (this.keepaliveHandle === null)
+            return;
+        this.cancel(this.keepaliveHandle);
+        this.keepaliveHandle = null;
+    }
+    /** 起保活（schedule 缺席 = 缺位；触发后清位自重排续针——周期重发维持） */
+    armKeepalive() {
+        if (this.schedule === null || this.keepaliveHandle !== null)
+            return;
+        this.keepaliveHandle = this.schedule(() => {
+            this.keepaliveHandle = null;
+            this.io.write(PROGRESS_ACTIVE_SEQUENCE); // 周期重发（超时衰减型终端维持）
+            this.armKeepalive();
+        }, OSC_PROGRESS_KEEPALIVE_MS);
+    }
+}