berry-agent 0.1.0-alpha.1

package/dist/channels/tui/status/status-line.js

@@ -0,0 +1,76 @@
+import { ansiColor } from '../../engine/index.js';
+import { ACCENT_INDEX } from '../theme.js';
+/** 转轮帧序（braille 十帧——accent 呈现形态随组件批定形，本批定形） */
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/** 转轮样式（accent 定值——theme 单源） */
+const SPINNER_STYLE = Object.freeze({ fg: ansiColor(ACCENT_INDEX) });
+/** 状态行动画件（量高恒 1 行——底部固定区状态行） */
+export class StatusLine {
+    /** 状态变更通知（装配层接重绘请求——start/stop/setTool/setStatus/tick） */
+    onChange;
+    busy = false;
+    /** 忙态文案（agent_start 附带的活动描述——工具名在场时让位） */
+    busyText = '';
+    /** 闲态文案（setStatus last-writer-wins——忙时写入挂起、闲时呈现） */
+    idleText = '';
+    /** 实时工具名（tool_execution_start 写入；null = 无工具在场） */
+    toolName = null;
+    frameIndex = 0;
+    /** 量高：恒 1（状态行单行制） */
+    measure(width) {
+        void width;
+        return 1;
+    }
+    /** 落位：忙态 = 转轮（accent）+ 工具段/活动文案；闲态 = 文案行（空则空行） */
+    render(buffer, region) {
+        if (this.busy) {
+            const frame = SPINNER_FRAMES[this.frameIndex % SPINNER_FRAMES.length];
+            buffer.writeText(region.row, region.col, frame, SPINNER_STYLE);
+            // 转轮后文案段（rest 自带前导空格——起点 = 转轮格 +1；工具名优先——件 3 语义）
+            const rest = this.toolName !== null ? ` ⚙ ${this.toolName} …` : this.busyText !== '' ? ` ${this.busyText}` : '';
+            if (rest !== '')
+                buffer.writeText(region.row, region.col + 1, rest);
+        }
+        else if (this.idleText !== '') {
+            buffer.writeText(region.row, region.col, this.idleText);
+        }
+    }
+    /** 进入忙态（agent_start 驱动；text = 可选活动描述） */
+    start(text = '') {
+        this.busy = true;
+        this.busyText = text;
+        this.toolName = null;
+        this.onChange?.();
+    }
+    /** 退出忙态（agent_end 驱动——工具名一并清） */
+    stop() {
+        this.busy = false;
+        this.toolName = null;
+        this.onChange?.();
+    }
+    /** 忙态观测（装配层布防抖逻辑用） */
+    get isBusy() {
+        return this.busy;
+    }
+    /** 实时工具名（tool_execution_start → name；null 清——工具退场） */
+    setTool(name) {
+        this.toolName = name;
+        this.onChange?.();
+    }
+    /** 闲态文案（last-writer-wins——usage 行与自定义状态同载体共存） */
+    setStatus(text) {
+        this.idleText = text;
+        this.onChange?.();
+    }
+    /** 推帧（装配层定时驱动——仅忙态有意义；闲态推帧零变化零通知） */
+    tick() {
+        if (!this.busy)
+            return;
+        this.frameIndex++;
+        this.onChange?.();
+    }
+    /** 当前转轮帧观测面（测试断言帧推进用） */
+    get frame() {
+        return SPINNER_FRAMES[this.frameIndex % SPINNER_FRAMES.length];
+    }
+}

package/dist/channels/tui/text.js

@@ -0,0 +1,38 @@
+import { truncateToWidth, wrapText } from '../engine/index.js';
+/** 单行文本件（measure 恒 1；宽字符截断不产半字） */
+export class Text {
+    content;
+    style;
+    constructor(props) {
+        this.content = props.content;
+        this.style = props.style;
+    }
+    measure(_width) {
+        return 1;
+    }
+    render(buffer, region) {
+        if (region.width <= 0 || region.height <= 0)
+            return;
+        buffer.writeText(region.row, region.col, truncateToWidth(this.content, region.width), this.style);
+    }
+}
+/** 折行文本件（显式 \n + 列宽折行；measure = 折行行数——两段同一 wrapText 单源） */
+export class Paragraph {
+    content;
+    style;
+    constructor(props) {
+        this.content = props.content;
+        this.style = props.style;
+    }
+    measure(width) {
+        return wrapText(this.content, Math.max(1, width)).length;
+    }
+    render(buffer, region) {
+        if (region.width <= 0 || region.height <= 0)
+            return;
+        const lines = wrapText(this.content, region.width);
+        for (let i = 0; i < Math.min(lines.length, region.height); i++) {
+            buffer.writeText(region.row + i, region.col, lines[i] ?? '', this.style);
+        }
+    }
+}

package/dist/channels/tui/theme.js

@@ -0,0 +1,41 @@
+/**
+ * TUI 呈现配色面（07 篇 §4.1 引擎节件 3「着色克制」条款的定值件）。
+ *
+ * 着色纪律单源（引擎节件 3）：accent 只用于焦点指示面（现载体 = 对话输入件
+ * 焦点边框、状态行转轮、overlay 占焦族〔select 面板标题 + 补全弹层空态〕
+ * ——2026-09-07 实装对账补列），正文不混用（唯一例外 = 非聚焦摘要行的会话区分色
+ * ——非 accent 家族的第二着色位，见 sessionColor）；accent 无用户配置面——
+ * v1 固定内置色板、缺省索引在本件定值（「随组件批定值」的兑现位）。
+ */
+import { ansiColor } from '../engine/index.js';
+/**
+ * accent 缺省色号（v1 定值 = cyan 6）。
+ *
+ * 选型依据：cyan 是 16 色板经典强调色，与常见终端配色（暗底浅字）对比稳定；
+ * 索引 6 属标准 8 色，8 色降级终端（07 §4.1 支持矩阵——bold 亮色映射兜底）
+ * 下仍可辨。真彩 / 256 色升级挂账引擎节件 3，届时本值随色板扩展再裁。
+ */
+export const ACCENT_INDEX = ansiColor(6);
+/**
+ * FNV-1a 32 位散列（会话区分色的确定性散列源——无依赖、分布均匀、同输入
+ * 恒同输出；charCodeAt 按 UTF-16 码元——短 id 十六进制串场景无代理对歧义）。
+ */
+function fnv1a(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+/**
+ * 会话区分色：会话短 id 散列映射 16 色板索引（07 引擎节件 3——确定性纯
+ * 函数、零配置零存储；berry themeFor「各归各色」的等价承接，主题配置面
+ * 不预造）。消费面 = 非聚焦摘要行着色（呈现面件 9），与 accent 家族互斥。
+ *
+ * 映射域 = 16 色板全域（含索引 0——黑底终端上可读性弱是已知取舍，按规范
+ * 字面全域映射；真实痛感出现时随色板升级挂账一并再裁）。
+ */
+export function sessionColor(sessionShortId) {
+    return ansiColor(fnv1a(sessionShortId) & 0x0f);
+}

package/dist/channels/types.js

@@ -0,0 +1,11 @@
+/**
+ * channels 件类型契约（L4 宿主固定件——02 篇席 10；机制真源 07 篇 §4.1/§4.3、
+ * 03 篇 §2.2 命令面、04 篇 §4 队列、04 篇 §9 审批归属）。
+ *
+ * 批 10a 落通道核（多会话信封分流 + 投影拉取注入 + 命令面 + ui 原语分发 +
+ * 提问队列——通道无关逻辑，零渲染依赖〔2026-09-06 改裁弃 pi-tui 后天然
+ * 满足——TUI 实装已落件内自研栈，批 10e〕）。
+ * 单向 DAG：channels → contracts, context, agent（02 §4.1——投影类型经装配侧
+ * 泛型钉入，不 import session）。
+ */
+export {};

package/dist/channels/ui-core.js

@@ -0,0 +1,209 @@
+/**
+ * ui 原语分发核（07 §4.3 签名定稿的通道无关编排面——2026-09-06 channels 纵切批）。
+ *
+ * 职责三块：①降级判定——通道不支持的原语按「notify 化」降级
+ * （select→input→notify、confirm→input→notify——插件不感知通道能力差异）；
+ * ②阻塞原语编排——入提问队列（与审批 ask 同队列）+ 多后端并发竞速
+ * （04 §9 跨入口先答先得，败腿经 signal 撤销）；③widget 会话级单槽
+ * （后写胜前写、置 null 清空——07 §4.3 setWidget 多写者语义）。
+ *
+ * 撤销面（07 §4.3）：外部 signal abort 或队列收口 → 保守值收场
+ * （confirm→false / select·input→''）——曾在屏者的撤销说明行归后端
+ * signal 消费实现，核只负责 abort 传播与结算。
+ *
+ * 核级 API 一律显式 sessionId（多会话归属的机器位）；ctx.ui 薄包装绑
+ * 「当前会话」归 host 装配批。后端移除（removeBackend）时在飞问询的收口
+ * 是后端自身义务（移除前 settle 或经 signal abort）——装配级事件，核不代管。
+ */
+import { AskQueue } from './ask-queue.js';
+export class UiCore {
+    backendsGetter;
+    askQueue;
+    /** 审批 always 的策略表回写注入（07 §4.3 提问队列条款——装配接线） */
+    onApprovalAlways;
+    /** widget 会话级单槽（07 §4.3——per-session 恰一槽，后写胜前写） */
+    widgets = new Map();
+    constructor(backendsGetter, askQueue, onApprovalAlways) {
+        this.backendsGetter = backendsGetter;
+        this.askQueue = askQueue;
+        this.onApprovalAlways = onApprovalAlways;
+    }
+    backends() {
+        return this.backendsGetter();
+    }
+    /** 能力过滤：声明且实现俱在才 capable（防后端声明能力而缺实现——防御位） */
+    capable(cap) {
+        // 能力键与方法名同名惯例的唯一例外：approval 位的方法面叫 askApproval
+        //（与服务面同名——UiBackend 上 confirm/select/input 三件方法名即能力名）
+        const method = cap === 'approval' ? 'askApproval' : cap;
+        return this.backends().filter((b) => b.capabilities[cap] === true && typeof b[method] === 'function');
+    }
+    // ---- 非阻塞三件（纯活体层——07 §4.3 语义纪律：不落日志不入队） ----
+    /** 一次性通知：扇出全部后端（level 档识别与 info 归一归后端呈现侧） */
+    notify(message, opts) {
+        for (const b of this.backends()) {
+            if (b.capabilities.notify)
+                b.notify(message, opts);
+        }
+    }
+    /** 状态行更新：扇出 capable 后端（last-writer-wins 天然）；零 capable no-op */
+    setStatus(sessionId, status) {
+        for (const b of this.capable('setStatus'))
+            b.setStatus?.(sessionId, status);
+    }
+    /** widget 单槽：后写胜前写、置 null 清空；扇出 capable 后端 */
+    setWidget(sessionId, node) {
+        if (node === null) {
+            this.widgets.delete(sessionId);
+        }
+        else {
+            this.widgets.set(sessionId, { node });
+        }
+        for (const b of this.capable('setWidget'))
+            b.setWidget?.(sessionId, node);
+    }
+    /** 当前槽值（repaint 载荷消费——焦点切换重画带上该会话槽） */
+    widgetOf(sessionId) {
+        return this.widgets.get(sessionId) ?? null;
+    }
+    /** 观众探针：任一后端自报有观众（TUI 恒真 / webui 在线连接数 > 0 / 零后端即假） */
+    hasAudience() {
+        return this.backends().some((b) => b.hasAudience());
+    }
+    // ---- 阻塞三件（入提问队列——与审批 ask 同队列 per-session FIFO） ----
+    /** 是/否确认（降级链：confirm 后端 → input 后端〔(y/n) 形〕→ notify 化 + 保守值 false） */
+    confirm(sessionId, message, opts) {
+        return this.ask(sessionId, 'confirm', opts?.signal, () => false, (signal) => {
+            const direct = this.capable('confirm');
+            if (direct.length > 0) {
+                return Promise.race(direct.map((b) => b.confirm(message, { signal })));
+            }
+            const viaInput = this.capable('input');
+            if (viaInput.length > 0) {
+                // confirm→input 降级（07 §4.3 降级路径同链透传）：(y/n) 形、答 y/yes 为真
+                const prompt = `${message} (y/n)`;
+                return Promise.race(viaInput.map((b) => b.input(prompt, { signal }))).then((answer) => /^y(es)?$/i.test(answer.trim()));
+            }
+            // notify 化到底：呈现问句后保守值收场（无人可答——fail-closed）
+            this.notify(message);
+            return Promise.resolve(false);
+        });
+    }
+    /** 单选（降级链：select 后端 → input 后端〔编号列表形〕→ notify 化 + 保守值 ''） */
+    select(sessionId, message, choices, opts) {
+        return this.ask(sessionId, 'select', opts?.signal, () => '', (signal) => {
+            const direct = this.capable('select');
+            if (direct.length > 0) {
+                return Promise.race(direct.map((b) => b.select(message, choices, { signal }))).then((answer) => validateChoice(answer, choices));
+            }
+            const viaInput = this.capable('input');
+            if (viaInput.length > 0) {
+                // select→input 降级（Web 通道维持同款——07 §4.3）：编号列表提示、手输 value
+                const prompt = `${message}\n${choices.map((c, i) => `${i + 1}. ${c.label} → ${c.value}`).join('\n')}`;
+                return Promise.race(viaInput.map((b) => b.input(prompt, { signal }))).then((answer) => validateChoice(answer, choices));
+            }
+            this.notify(`${message}\n${choices.map((c) => `- ${c.label} → ${c.value}`).join('\n')}`);
+            return Promise.resolve('');
+        });
+    }
+    /** 自由文本输入（降级链：input 后端 → notify 化 + 保守值 ''） */
+    input(sessionId, message, opts) {
+        return this.ask(sessionId, 'input', opts?.signal, () => '', (signal) => {
+            const viaInput = this.capable('input');
+            if (viaInput.length > 0) {
+                return Promise.race(viaInput.map((b) => b.input(message, { placeholder: opts?.placeholder, signal })));
+            }
+            this.notify(message);
+            return Promise.resolve('');
+        });
+    }
+    /**
+     * 审批 ask（07 §4.3 提问队列条款——与阻塞三件同队同收口律）：
+     * 多后端竞速先答先得（跨入口单漏斗——decide durable 单漏斗在
+     * ApprovalService 不变）；收口两语义分立（对齐 04 §9 run 信号透传
+     * ask 链）——会话关闭 / run 打断 → `'cancel'`（用户主动终止）；降级
+     * 到底（全部后端无 approval capability）→ `'unavailable'`（呈现面
+     * 结构性无人可答——ApprovalService 侧落 timeout 源；2026-09-13 真模型
+     * 实测批修，修前误答 'cancel' 错标用户主动取消）；`always` + 草案 →
+     * onApprovalAlways 回写；无草案 always 防御收口视同 approve（零草案
+     * 零副作用）。
+     */
+    askApproval(sessionId, request, opts) {
+        return this.ask(sessionId, 'approval', opts?.signal, () => 'cancel', (signal) => {
+            const direct = this.capable('approval');
+            if (direct.length > 0) {
+                return Promise.race(direct.map((b) => b.askApproval(sessionId, request, { signal }))).then((answer) => this.settleApprovalAlways(answer, request));
+            }
+            // notify 化到底：呈现摘要后自报结构性无人（fail-closed——04 §9 无应答
+            // 者语义，ApprovalService 落 unavailable/timeout；与打断路保守值 'cancel'
+            // 分立——修前误答 'cancel' 致 decided 错标 cancel/user 双失真）
+            this.notify(request.summary);
+            return Promise.resolve('unavailable');
+        });
+    }
+    /** always 收口路：带草案回写策略表注入面；无草案防御视同 approve */
+    settleApprovalAlways(answer, request) {
+        if (answer !== 'always')
+            return answer;
+        if (request.suggestedEntry === undefined)
+            return 'approve'; // 零草案零副作用（04 §9 ③）
+        this.onApprovalAlways?.(request.suggestedEntry);
+        return 'always';
+    }
+    // ---- 收口 ----
+    /**
+     * 会话收口（通道侧——unregisterSession 联动）：清提问队列（余项保守值）+
+     * 清 widget 槽。后端各自的会话呈现清理由其后端自身负责（onEnvelope 流断）。
+     */
+    closeSession(sessionId) {
+        this.askQueue.clearSession(sessionId);
+        this.widgets.delete(sessionId);
+    }
+    /** 提问队列观察面（透传——诊断面/测试消费） */
+    pending(sessionId) {
+        return this.askQueue.pending(sessionId);
+    }
+    // ---- 编舞内核 ----
+    /**
+     * ask 统一编排：入队 → 队首呈现（多后端竞速先答先得）→ 落定出队。
+     * 入口先收副屏（07 §4.1 件 8 条款：注意力优先级 ask > 回看——ask 到来时
+     * 在场副屏先收起再入提问队列；能力缺席〔无副屏后端〕零义务跳过）。
+     * 三条收口路（全部 once）：首答（含降级解析值）/ 呈现异常（保守值——
+     * fail-closed）/ 外部 signal abort 或队列取消（保守值）。
+     */
+    ask(sessionId, kind, externalSignal, conservative, present) {
+        // ask 强制收起（件 8 条款——批 10f-4）：扇出可选钩，先于入队
+        for (const b of this.backends())
+            b.collapseAltScreen?.();
+        let resolve;
+        const promise = new Promise((r) => {
+            resolve = r;
+        });
+        let done = false;
+        // 内部 signal：败腿撤销 + 队列收口的统一传播位（后端只认这一个信号源——
+        // 外部 signal 经本核折入 finish，不直传后端）
+        const controller = new AbortController();
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            controller.abort(); // 败腿撤销传播（已落定后端再收 abort 是无害 no-op）
+            resolve(value);
+            this.askQueue.settled(sessionId);
+        };
+        const externalAbort = () => finish(conservative());
+        externalSignal?.addEventListener('abort', externalAbort, { once: true });
+        this.askQueue.enqueue(sessionId, kind, {
+            start: () => {
+                present(controller.signal).then(finish, () => finish(conservative()));
+            },
+            cancel: () => finish(conservative()),
+        });
+        return promise;
+    }
+}
+/** select 降级答案校验：手输不在 value 集即保守值 ''（fail-closed——不猜最近匹配） */
+function validateChoice(answer, choices) {
+    const trimmed = answer.trim();
+    return choices.some((c) => c.value === trimmed) ? trimmed : '';
+}

package/dist/checkpoint/capture.js

@@ -0,0 +1,45 @@
+/**
+ * checkpoint 捕获执行（05 §5.3 批 15d——walk+hash+落仓+裁剪的单遍编舞）。
+ *
+ * 捕获序：枚举 walk 域（walk.ts 判据）→ 逐文件单遍读+哈希（读一次同时喂
+ * blob 写与 manifest 条目——无双读）→ blob 落仓（内容寻址去重）→ manifest
+ * 落仓 → prune（per workspace 保留帽 + blob 引用计数 GC）。
+ *
+ * 失败语义：walk/读文件/blob 写任一失败抛 CHECKPOINT_CAPTURE_FAILED——
+ * gate 侧折 fail-closed block（快照是 rewind 语义承诺的前提，拍不了就放行
+ * 变异 = 伪承诺）。空工作区合法（files: [] 的 manifest——恢复到空也是回退点）。
+ */
+import { randomUUID } from 'node:crypto';
+import { contentHash } from './store.js';
+import { readWorkspaceFile, walkWorkspaceFiles } from './walk.js';
+/** 组装捕获面（openCheckpointStore 的伴生件——装配根一并接线） */
+export function createCapture(store, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const newId = opts.newId ?? randomUUID;
+    return async ({ sessionId, boundarySeq, workspaceRoot, trigger }) => {
+        // 段一：枚举 + 单遍读哈希（IO 失败由 walk/readWorkspaceFile 折 CAPTURE_FAILED）
+        const walked = await walkWorkspaceFiles(workspaceRoot);
+        const entries = [];
+        for (const file of walked) {
+            const content = await readWorkspaceFile(file.absPath);
+            const hash = contentHash(content);
+            await store.writeBlob(hash, content);
+            entries.push({ path: file.path, hash, bytes: content.byteLength });
+        }
+        // 段二：manifest 落仓（id = uuid——/rewind 作用目标键）
+        const manifest = {
+            id: newId(),
+            sessionId,
+            boundarySeq,
+            workspaceRoot,
+            capturedAt: now(),
+            trigger,
+            files: entries,
+        };
+        await store.saveManifest(manifest);
+        // 段三：裁剪编舞（每次捕获后跑——保留帽 + 引用计数 GC；失败不回滚本次
+        // 落仓：prune 是维护面，异常上抛交调用方诊断，快照本体已原子在册）
+        await store.prune();
+        return manifest;
+    };
+}

package/dist/checkpoint/codes.js

@@ -0,0 +1,33 @@
+/**
+ * checkpoint 域错误码注册（05 §5.3——CHECKPOINT_ 前缀族；02 §5.3 批 15d
+ * 明列四码）。
+ *
+ * 码语义分层：CAPTURE_FAILED 管 pre-mutation 捕获 fail-closed（快照是
+ * rewind 语义承诺的前提）；NOT_FOUND 管回退点缺席守卫；STORE_CORRUPT 管
+ * 快照仓坏形 fail-loud（宁拒不误读）；RESTORE_FAILED 管恢复执行 IO 失败
+ * （pre-rewind 保底快照在场可重跑收敛）。本文件由模块公开面 index.ts
+ * 引入（注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'CHECKPOINT_CAPTURE_FAILED',
+        module: 'checkpoint',
+        description: 'pre-mutation 捕获失败——守门段 fail-closed block 位（拍不了就放行变异 = 伪承诺；含 walk 超文件帽）',
+    },
+    {
+        code: 'CHECKPOINT_NOT_FOUND',
+        module: 'checkpoint',
+        description: '回退点缺席——已裁剪或坏 id（/rewind 作用目标守卫）',
+    },
+    {
+        code: 'CHECKPOINT_STORE_CORRUPT',
+        module: 'checkpoint',
+        description: '快照仓坏形——manifest 坏形或 blob 哈希不符，fail-loud 拒误读',
+    },
+    {
+        code: 'CHECKPOINT_RESTORE_FAILED',
+        module: 'checkpoint',
+        description: '恢复执行 IO 失败——pre-rewind 保底快照在场，重跑同 manifest 幂等收敛',
+    },
+]);

package/dist/checkpoint/command.js

@@ -0,0 +1,82 @@
+/**
+ * /rewind 命令处理器（05 §5.3 批 15d——两段事务的用户呈现面）。
+ *
+ * 形态律与 /goal、/tick 同族：argv → 人读文本；服务面守卫错（BaseError：
+ * NOT_FOUND / STORE_CORRUPT / RESTORE_FAILED）折文本不抛（命令面是用户面
+ * 不是异常面）。动词三形：
+ *   /rewind list            按当前会话工作区锚列点（id/时刻/触发形/规模）
+ *   /rewind preview <id>    段一 preview——恢复 N/删除 M/不动 U 零改动对账
+ *   /rewind restore <id>    段二 restore——保底拍+文件恢复+fork 三步序
+ *
+ * TUI 命令注册已落（批 19c-4 ctx.channels.registerCommand）；adopt 切前台
+ * 编舞 v1 未落——restore 回执的 forkedSessionId 先经输出面呈报，焦点切换随
+ * TUI adopt 命令立题〔2026-09-11 勘正：原注指向已飞的批 12，失锚〕。
+ */
+import { BaseError } from '../contracts/index.js';
+import { previewRewind, restoreRewind } from './restore.js';
+export const REWIND_USAGE = [
+    '用法：/rewind list —— 列当前工作区的回退点',
+    '　　　/rewind preview <id> —— 预演（恢复 N/删除 M/不动 U，零改动）',
+    '　　　/rewind restore <id> —— 回退（保底快照 → 文件恢复 → fork 新会话）',
+].join('\n');
+/** manifest 行渲染（list 用——id 截 8 位短形 + 触发形中文 + 规模） */
+function manifestLine(id, capturedAt, trigger, files, boundarySeq) {
+    const when = new Date(capturedAt).toISOString().replace('T', ' ').slice(0, 19);
+    const kind = trigger === 'mutation' ? '变异前拍' : '回退保底拍';
+    return `- ${id.slice(0, 8)}… ${when}〔${kind}〕${files} 文件 · 回退点 seq=${boundarySeq}`;
+}
+/** /rewind 处理器（argv → 人读文本；守卫错折文本） */
+export async function runRewindCommand(argv, deps) {
+    const [verb, ...rest] = argv;
+    try {
+        switch (verb) {
+            case 'list': {
+                const ctx = deps.session.contextOf(deps.sessionId);
+                if (ctx === undefined || ctx.workspaceRoot === '') {
+                    return '当前会话无工作区锚——无从列点（快照特性按工作区适用）。';
+                }
+                const rows = (await deps.store.listManifests()).filter((m) => m.workspaceRoot === ctx.workspaceRoot);
+                if (rows.length === 0)
+                    return '本工作区暂无回退点（首个变异前拍在工作区内的写工具执行时落）。';
+                const lines = rows.map((m) => manifestLine(m.id, m.capturedAt, m.trigger, m.files.length, m.boundarySeq));
+                return `本工作区共 ${rows.length} 个回退点（新在前）：\n${lines.join('\n')}`;
+            }
+            case 'preview': {
+                const id = rest[0];
+                if (!id)
+                    return `缺回退点 id。\n${REWIND_USAGE}`;
+                const result = await previewRewind(deps.store, id);
+                return [
+                    `回退点 ${result.manifest.id.slice(0, 8)}…（${new Date(result.manifest.capturedAt).toISOString().replace('T', ' ').slice(0, 19)} 拍摄，${result.manifest.files.length} 文件，回退点 seq=${result.manifest.boundarySeq}）`,
+                    `预演对账（零改动）：恢复 ${result.restoreCount} · 删除 ${result.deleteCount} · 不动 ${result.untouchedCount}`,
+                    `确认执行：/rewind restore ${result.manifest.id}`,
+                ].join('\n');
+            }
+            case 'restore': {
+                const id = rest[0];
+                if (!id)
+                    return `缺回退点 id。\n${REWIND_USAGE}`;
+                const receipt = await restoreRewind(deps, id);
+                const forkLine = receipt.forkedSessionId !== undefined
+                    ? `已 fork 新会话 ${receipt.forkedSessionId}（旧史保留，自回退点净边界起跑）。`
+                    : `fork 未成：${receipt.vetoReason}（文件已恢复——痕迹链完整，可重试或手动接续）`;
+                return [
+                    `已回退至 ${receipt.id.slice(0, 8)}…：恢复 ${receipt.restoredCount} · 删除 ${receipt.deletedCount} · 不动 ${receipt.untouchedCount}`,
+                    `保底快照 ${receipt.preRewindId.slice(0, 8)}…（本次回退自身可回退）。`,
+                    forkLine,
+                ].join('\n');
+            }
+            case undefined:
+            case 'help':
+                return REWIND_USAGE;
+            default:
+                return `未知动词「${verb}」。\n${REWIND_USAGE}`;
+        }
+    }
+    catch (err) {
+        // 守卫错折文本（命令面是用户面——BaseError 码与人读原因直呈）
+        if (err instanceof BaseError)
+            return `${err.code}：${err.message}`;
+        throw err;
+    }
+}

package/dist/checkpoint/gate.js

@@ -0,0 +1,48 @@
+/**
+ * 组装守门监听器（工厂——监听器闭包内持 per-session 边界游标 Map，跨调用
+ * 存活；同一 dispatch 生命周期内复用一个实例，重复挂载 = 各自独立游标）。
+ */
+export function createCheckpointGate(deps) {
+    const warn = deps.warn ?? ((message) => console.warn(message));
+    // per-session 上次捕获边界（per-run 判据的游标——turn 在飞边界不动即同 run）
+    const lastCapturedBoundary = new Map();
+    return async (input, next) => {
+        // 判据 1：只管写意图（read 工具不触发快照——03 §2.3 effect 面）
+        if (input.tool.effect !== 'write')
+            return next(input);
+        // 判据 2：无会话键 = 非本件域（测试/系统调用形态——静默放行）
+        const sessionId = input.sessionId;
+        if (sessionId === undefined)
+            return next(input);
+        // 判据 2b：会话语境不可解（contextOf undefined）同上放行——不 warn
+        // （会话未知是装配面事实，非配置缺口；两分见判据 3）
+        const ctx = deps.session.contextOf(sessionId);
+        if (ctx === undefined)
+            return next(input);
+        // 判据 3：无 workspaceRoot 锚 = 配置缺口——放行 + warn（非仓故障）
+        if (ctx.workspaceRoot === '') {
+            warn(`[checkpoint] 会话 ${sessionId} 无工作区锚——快照不适用，写工具放行（配置缺口：会话建时未带 workspaceRoot）。`);
+            return next(input);
+        }
+        // 判据 4：边界未推进 = 同 run 段——不重拍（per-run 一 manifest）
+        const boundary = ctx.lastClosedBoundary;
+        const last = lastCapturedBoundary.get(sessionId);
+        if (last !== undefined && boundary <= last)
+            return next(input);
+        // 捕获（mutation 拍）：失败折 fail-closed block——reason 首缀专属码
+        try {
+            await deps.capture({ sessionId, boundarySeq: boundary, workspaceRoot: ctx.workspaceRoot, trigger: 'mutation' });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            input.outcome = {
+                action: 'block',
+                reason: `[CHECKPOINT_CAPTURE_FAILED] pre-mutation 快照失败，fail-closed 拒变异（快照是回退承诺的前提）：${message}`,
+            };
+            return input; // 不调 next：短路整链（守门段 block 语义）
+        }
+        // 成功：推进游标（后续同 run 写工具不再重拍）+ 放行交棒
+        lastCapturedBoundary.set(sessionId, boundary);
+        return next(input);
+    };
+}

package/dist/checkpoint/index.js

@@ -0,0 +1,20 @@
+/**
+ * checkpoint 模块公开面（05 §5.3 批 15d——工作区快照/回退件）。
+ *
+ * 消费面（批 19c-4 装载态入册兑现）：gate 监听器（core:checkpoint 件经
+ * 插件钩子正门 ctx.on('tools_pre_execute') 挂 waterfall——装载期注册先于
+ * per-session safety 行，序差无害注记见 core-plugins.ts 装配序注记）+
+ * /rewind 命令（ctx.channels.registerCommand——发起会话 = 焦点会话；
+ * adopt 切前台编舞 v1 未落——restore 回执的 forkedSessionId 先经命令输出
+ * 面呈报，焦点切换随 TUI adopt 命令立题〔2026-09-11 遗漏扫描批勘正——
+ * 原注指向已飞的 run 入口批，失锚〕）。codes.js 的 import 副作用 = 错误码
+ * 注册纪律（import 发生才注册）。
+ */
+import './codes.js';
+export { CHECKPOINT_RETENTION_PER_WORKSPACE, CHECKPOINT_WALK_FILE_CAP, } from './types.js';
+export { readWorkspaceFile, walkWorkspaceFiles } from './walk.js';
+export { contentHash, openCheckpointStore } from './store.js';
+export { createCapture } from './capture.js';
+export { createCheckpointGate } from './gate.js';
+export { previewRewind, restoreRewind, } from './restore.js';
+export { REWIND_USAGE, runRewindCommand } from './command.js';