berry-agent 0.1.0-alpha.1

package/dist/host/serve-entry.js

@@ -0,0 +1,279 @@
+import { Readable } from 'node:stream';
+import { stdin, stdout, stderr } from 'node:process';
+import { createSdkBackend, decodeWireLine, encodeWireLine, isSdkRequest, splitWireLines } from '../channels/index.js';
+import { assembleHostStack } from './assembly.js';
+import { startSchedulerClock } from './core-plugins.js';
+import { openWebuiFace } from './webui-bridge.js';
+/**
+ * 会话事件 → durable 平铺投影（双轨律重放段载体——type/seq/time/data 四字段
+ * 原样平铺，词汇零二校验〔05 §3.5 第一腿〕）。
+ */
+function toDurableEntry(event) {
+    return { type: event.type, seq: event.seq, time: event.time, data: event.data };
+}
+/**
+ * 装配桥：ConversationStack → SdkWireDeps 桥接（05 §3.5 serve 外推三腿的
+ * 桥接位；导出面供 serve-entry 传输环消费与组装级测试直测）。
+ *
+ * 映射律（在册会话内存日志优先——write-behind 在飞事件的权威源；未开会话
+ * 走库面纯读不 attach）：
+ * - submitPrompt：sessionId 缺席 manager.create 新建（workspaceRoot 锚 cwd）、
+ *   显式携带 manager.open 落驱动（幂等续接；missing/closed 已被线核先决门
+ *   拦截）；routedChannel 按受理时刻 driver.running 推导（03 §10.6 注记）；
+ *   归因 `channel:sdk` + messageId→dedupeKey 落账（05 §3.5 两词一字段两面）。
+ * - queryEntries：单页全窗（重放腿跟尽 nextCursor 义务由桥并页兑现——cursor
+ *   形参 v1 无第二页可续）。
+ * - highWaterOf：在册 = 内存日志长度；未开 = 行 lastSeq（= 末次落账事件数）。
+ */
+export function createServeBridge(stack, runtime, anchors) {
+    /** 会话日志权威读（在册走内存——含 write-behind 在飞；未开走库面纯读） */
+    const logOf = (sessionId) => {
+        const driver = stack.driverOf(sessionId);
+        if (driver !== undefined)
+            return driver.session.events();
+        return runtime.persistence.store.loadEvents(sessionId);
+    };
+    return {
+        submitPrompt: (input) => {
+            let sessionId = input.sessionId;
+            if (sessionId === undefined) {
+                sessionId = stack.manager.create({ workspaceRoot: anchors.cwd }).sessionId;
+            }
+            // 显式会话可能仅库面在册——open 幂等落驱动（线核先决门已拦 missing/closed）
+            const driver = stack.driverOf(sessionId) ?? stack.manager.open(sessionId).driver;
+            // routedChannel 观察推导（03 §10.6 注记：受理时刻在飞 run → steer、否则
+            // followUp——驱动侧单源路由的受理时刻投影，非控制位）
+            const routedChannel = driver.running ? 'steer' : 'followUp';
+            // 起跑让位一拍（queueMicrotask）：线核在 submitPrompt 返回后才同步挂
+            // 自动订阅——同步起跑会让 agent_start 先于订阅点入空（首帧丢）。让位
+            // 一拍保证订阅点先落、直播自 agent_start 起。回执经信封回流；回执面
+            // 错误经 submitText 内部 notify 收口（无未处理拒绝）
+            queueMicrotask(() => {
+                stack.submitText(sessionId, input.content, {
+                    source: 'channel:sdk',
+                    dedupeKey: input.messageId,
+                });
+            });
+            return { sessionId, routedChannel };
+        },
+        lookupDedupeKey: (sessionId, messageId) => {
+            // durable 档查重（05 §3.5 第二腿）：返回原内容串——admit 同键异内容
+            // 判定源；块形内容（非 serve 线来源理论不达）JSON 稳定化兜底
+            for (const event of logOf(sessionId)) {
+                if (event.type !== 'user/message')
+                    continue;
+                const data = event.data;
+                if (data.dedupeKey !== messageId)
+                    continue;
+                return typeof data.content === 'string' ? data.content : (JSON.stringify(data.content) ?? '');
+            }
+            return undefined;
+        },
+        interruptSession: (sessionId) => {
+            stack.interrupt(sessionId);
+        },
+        queryEntries: (sessionId, since) => {
+            const log = logOf(sessionId);
+            // (since, 高水位) 窗口（高水位 = 日志长度 = 下一 seq——线核同式）
+            return { entries: log.filter((e) => e.seq > since && e.seq < log.length).map(toDurableEntry) };
+        },
+        listSessions: () => stack.manager.list().map((row) => ({
+            id: row.id,
+            title: row.title ?? null, // 无标题不造占位串（03 §10.6 sessions 词面）
+            lastActivityAt: row.updatedAt,
+        })),
+        highWaterOf: (sessionId) => {
+            const driver = stack.driverOf(sessionId);
+            if (driver !== undefined)
+                return driver.session.events().length;
+            const row = runtime.persistence.store.getSessionRow(sessionId);
+            return row === undefined ? undefined : row.lastSeq;
+        },
+        sessionStateOf: (sessionId) => {
+            const driver = stack.driverOf(sessionId);
+            if (driver !== undefined)
+                return driver.dismantled ? 'closed' : 'open';
+            // 库面在册 = 可续（prompt/订阅经 manager.open 落驱动）
+            return runtime.persistence.store.getSessionRow(sessionId) === undefined ? 'missing' : 'open';
+        },
+        retryProbeOf: (sessionId) => stack.driverOf(sessionId)?.retryState ?? null,
+    };
+}
+/**
+ * serve 主入口。阻塞至调用方收线（stdin EOF）/ 信号（经 main 编舞 →
+ * runtime.shutdown → closer）/ 传输面坏死 / 过载断连；返回进程退出码。
+ */
+export async function runServeEntry(options) {
+    // —— daemon 防御拒（13e-3 起 daemon 编舞归 main 分派层 → serve-daemon 件：
+    // spawner spawn 自镜像 + HTTP 面常驻。本入口只承载 stdio 前台形态——直调
+    // 传 daemon:true = 绕过分派层的编程误用，诚实拒不静默降级。占标记前拒——
+    // 不留半开场）——
+    if (options.flags.daemon) {
+        stderr.write('--daemon 归 main 分派层（serve-daemon 编舞件）——serve-entry 只承载 stdio 前台形态\n');
+        return 1;
+    }
+    // —— 装配公共段（批 19a-3 迁 assembly 件——与 TUI 同一合成代码路径：
+    // 运行时→logger→共享根→栈→**插件装载**〔core 注册表 + enabled.yaml 真跑〕；
+    // 单活跃机/开库/清单损坏失败档归一 {ok:false}——干净退出不写 crash.log）——
+    const assembly = await assembleHostStack({
+        runtime: {
+            ...(options.dataDir !== undefined ? { dataDir: options.dataDir } : {}),
+            ...(options.memory === true ? { memory: true } : {}),
+        },
+        noPlugins: false,
+        debug: options.flags.debug,
+        version: options.version ?? '0.0.0-unknown',
+        ...(options.providers !== undefined ? { providers: options.providers } : {}),
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        ...(options.env !== undefined ? { env: options.env } : {}),
+        ...(options.sandboxMode !== undefined ? { sandboxMode: options.sandboxMode } : {}),
+        ...(options.onRuntime !== undefined ? { onRuntime: options.onRuntime } : {}),
+    });
+    if (!assembly.ok) {
+        // 两档呈报：crashed = 意外异常（crash.log 已在装配件内写）；干净退出档
+        // = 启动失败（单活跃机/开库/启用清单损坏——消息自带前缀）
+        stderr.write(`${assembly.crashed ? `serve 运行失败：${assembly.message}` : assembly.message}\n`);
+        return assembly.exitCode;
+    }
+    const { runtime, stack, logger, scope } = assembly;
+    let exitCode = 0;
+    try {
+        // —— scheduler 挂钟起钟（批 20c——长驻形编舞）：stdio 前台长驻同 TUI 律
+        // （件在场即起 + 停钟挂 closer——engine 真身定时器非 unref 不挂会拖活
+        // 进程；件缺席 no-op）——
+        startSchedulerClock(scope, runtime);
+        // —— --port 统一 HTTP 面 TCP 人面（18a-3' 三入口咬合；03 §10.4 host
+        // 接线）：stdio 线与 TCP 面并存双活——面承载 SPA + /api/* + /v1/* 三族
+        // （bridge 同走 createServeBridge 零第二套映射）；披露两行走 stderr
+        // （serve 前台披露通道）；closer 挂运行时退出序——EOF/信号/过载三路
+        // 收场同享面收口（LIFO 在 serve-backend 之前注册 = drain 晚于 stdio 线
+        // 收口——网络面先关）。批 19e 件在场执法：sdk 件缺席 = 面本体件禁用
+        // 语义族——warn 一行不开面（daemon 形拒启退 2 同族，前台形降级——
+        // stdio 传输本体不受累）；webui 件缺席 = 面开而 /api/* 404（mountKit
+        // 缺席形——openWebuiFace 内分档披露）——
+        if (options.flags.port !== undefined) {
+            const sdkKit = scope.tryGet('sdk-http-face');
+            if (sdkKit === undefined) {
+                stderr.write('warn：core:sdk 件未装载——--port 人面不开（07 §5 daemon 拒启同族；stdio 传输不受累）\n');
+            }
+            else {
+                const mountKit = scope.tryGet('webui-face-mount');
+                await openWebuiFace({
+                    stack,
+                    runtime,
+                    port: options.flags.port,
+                    ...(mountKit !== undefined ? { mountKit } : {}),
+                    // U5-2：插件道路由受理器经 core:sdk kit 透传（snapshot/attachFace）
+                    ...(sdkKit.pluginRoutes !== undefined ? { pluginRoutes: sdkKit.pluginRoutes } : {}),
+                    ...(options.onWebuiOpen !== undefined ? { onOpen: options.onWebuiOpen } : {}),
+                });
+            }
+        }
+        const io = options.io ?? { input: stdin, output: stdout };
+        const heartbeatIntervalMs = options.heartbeatIntervalMs ?? 5_000;
+        // —— 传输环状态（收场单次性由 settled 门保证）——
+        let settled = false;
+        let remainder = '';
+        let resolveExit;
+        const exited = new Promise((resolve) => {
+            resolveExit = resolve;
+        });
+        // 出站 sink：stdout 直写，false = 背压（帧入线核有界队列待 drain）
+        const sink = {
+            write: (frame) => {
+                try {
+                    return io.output.write(encodeWireLine(frame));
+                }
+                catch {
+                    // 同步写异常（ENOBUFS 族）按背压处理——'error' 事件位统一退避重试
+                    return false;
+                }
+            },
+        };
+        const bridge = createServeBridge(stack, runtime, { cwd: options.cwd ?? process.cwd() });
+        const handle = createSdkBackend({ ...bridge, sink, onOverload: () => shutdown(1) }, // 过载直写后宿主关传输（错误档退 1）
+        {
+            heartbeatIntervalMs,
+            initialConnectionNoDelta: options.flags.noDelta, // 07 §5 --no-delta 宿主立场缺省
+        });
+        stack.channels.addBackend(handle.backend); // 信封回流自动馈送（conversation-stack onEvent → emit）
+        // 心跳：装配层定时驱动（线核零自驱时钟——13b 纪律）；drain 同拍 belt
+        //（'drain' 事件为主路，定时兜底防事件丢失挂队列）
+        const heartbeatTimer = setInterval(() => {
+            handle.core.heartbeatTick();
+            handle.core.drain();
+        }, heartbeatIntervalMs);
+        // 收场序：清定时 → dispose（在飞 ask cancel + core.close）→ runtime 六步
+        // 退出序（幂等——EOF 路径与信号路径同享，closer 保证信号路径同样执行）
+        const shutdown = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearInterval(heartbeatTimer);
+            handle.dispose();
+            void runtime
+                .shutdown()
+                .catch(() => { }) // 六步退出序内部已 fail-loud 记账——收场不二次抛
+                .then(() => resolveExit(code));
+        };
+        runtime.registerCloser({ label: 'serve-backend', fn: () => shutdown(0) }); // 信号路径优雅档（settled 门幂等——过载/坏死路径自带 1 不被覆写）
+        // —— 入站环：分帧 → 解码 → 线核受理 ——
+        io.input.setEncoding?.('utf8');
+        io.input.on('data', (chunk) => {
+            if (settled)
+                return;
+            const split = splitWireLines(chunk, remainder);
+            remainder = split.remainder;
+            for (const line of split.lines) {
+                let decoded;
+                try {
+                    decoded = decodeWireLine(line);
+                }
+                catch (err) {
+                    // 坏行不杀连接（fail-loud 诊断在 stderr——协议鲁棒位）
+                    logger.warn(`行解码失败跳过：${err instanceof Error ? err.message : String(err)}`);
+                    continue;
+                }
+                if (!isSdkRequest(decoded)) {
+                    logger.warn('收到帧形行（服务端只受理请求行）——跳过');
+                    continue;
+                }
+                handle.core.handleRequest(decoded);
+            }
+        });
+        // EOF = 调用方收线——优雅收场；管道断裂同语义（无对端可写即服务终了）
+        io.input.on('end', () => shutdown(0));
+        io.input.on('close', () => shutdown(0));
+        io.input.on('error', (err) => {
+            logger.warn(`stdin 异常：${err.message}`);
+            shutdown(1);
+        });
+        // —— 出站背压恢复与传输面健康 ——
+        io.output.on('drain', () => {
+            if (!settled)
+                handle.core.drain();
+        });
+        io.output.on('error', (err) => {
+            if (settled)
+                return;
+            // ENOBUFS/EAGAIN 族 = 管道瞬时拥塞（pi output-guard 三件套执法位——
+            // 宿主 serve 即执法宿主）：退避重试 drain；其余 = 传输面坏死收场退 1
+            if (err.code === 'ENOBUFS' || err.code === 'EAGAIN') {
+                setTimeout(() => {
+                    if (!settled)
+                        handle.core.drain();
+                }, 50);
+                return;
+            }
+            logger.warn(`stdout 异常：${err.message}`);
+            shutdown(1);
+        });
+        exitCode = await exited;
+    }
+    catch (err) {
+        runtime.writeCrashLog(err); // 崩溃取证先行（memory 形跳过——件内语义）
+        stderr.write(`serve 运行失败：${err instanceof Error ? err.message : String(err)}\n`);
+        exitCode = 1;
+    }
+    return exitCode;
+}

package/dist/host/session-anchor.js

@@ -0,0 +1,41 @@
+/**
+ * 会话锚 ALS 件（07 §4.3 消费腿条款档位 2——交互动词族批 ix-2 落码）。
+ *
+ * 命令执行窗自动锚的实现载体：AsyncLocalStorage 语境继承语义——命令派生
+ * 的 fire-and-forget 尾链（Job 完成回调、定时器尾链等）保留锚，后台尾链
+ * 问「原会话」零自觉正确；**两处语境遮蔽**（装载器 apply 包裹位 + 钩子派发
+ * 包裹位）经 withoutSessionAnchor 显式清空——装载期（含命令触发的装载流
+ * 嵌套，如 /reload）与钩子语境结构性无自动锚（规范条款的执法位）。
+ *
+ * 注入侧 = tui-entry dispatchCommand 闭包（命令派发时锚聚焦会话）；消费
+ * 侧 = plugin-context ctx.ui 面（阻塞三件/setStatus/setWidget 的锚解析）；
+ * 遮蔽侧 = loader invokeApply + plugin-context withCallbackWindow。三侧同
+ * 模块（host），零拓扑新边。
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** 单例存储——store 形即锚本体（sessionId 只读） */
+const anchorStorage = new AsyncLocalStorage();
+/**
+ * 读 ambient 会话锚（无锚语境 = undefined——装载期/钩子期经遮蔽后恒此值）。
+ * ctx.ui 锚解析的缺省源：显式 opts.sessionId 优先、缺席回落本值。
+ */
+export function readSessionAnchor() {
+    return anchorStorage.getStore()?.sessionId;
+}
+/**
+ * 以会话锚执行 fn（命令派发包裹位——tui-entry dispatchCommand 闭包）。
+ * fn 同步返回值直通；async 语境跟随（fn 派生的整个异步链均见锚——
+ * 「锚随异步链继承」的机制本体）。
+ */
+export function runWithSessionAnchor(sessionId, fn) {
+    return anchorStorage.run({ sessionId }, fn);
+}
+/**
+ * 清空 ambient 锚执行 fn（两处语境遮蔽——07 §4.3 档位 2 规范条款执法位）。
+ * ALS.exit 语义：fn 执行段（含 async 续体）结构性无锚；fn 返回后外层
+ * 语境原样恢复（fire-and-forget 尾链自起时 ambient 锚自然回来——「锚判
+ * 随后自理」的边界即此）。
+ */
+export function withoutSessionAnchor(fn) {
+    return anchorStorage.exit(fn);
+}

package/dist/host/sessions-cmd.js

@@ -0,0 +1,219 @@
+/**
+ * host/sessions-cmd — `sessions` 子命令族 CLI 入口（07 §5 会话管理命令族；
+ * CLI 对等律射界 02 §2.3 多会话面；批 20d）。
+ *
+ * 五子动词分账（开库形态两分）：
+ *  - **读腿（list/search）+ 维护动词（reindex）——零装配直开库**：不开运行
+ *    时、不占单活跃机标记、不装载插件（同 serve status 只读豁免族——短命
+ *    查询/维护动词不是第二宿主实例）。开库走 Persistence 直开 + 宿主迁移链
+ *    尾单源（HOST_MIGRATION_TAIL——开库门禁按链 head 校验 user_version，
+ *    短链开真库会被同库拒降级运行，链必须与运行时全同）。reindex 是派生物
+ *    重建（05 §9「派生物不修不补——重建即修复」），写面只 session_fts 表。
+ *  - **fork——全装配**：与 run --fork / TUI fork 同机（assembly 公共段：
+ *    单活跃机占标记 + 插件装载——session_before_fork 钩子保真〔checkpoint
+ *    waterfall gate 等在场〕；05 §5.0 边界快照机制单源在 SessionManager.fork）。
+ *  - **resume <id>——进 TUI**：直托 runTuiEntry（resumeSessionId 载体——
+ *    「指定 id 续接」的 CLI 半边，与无参 TUI 的按 cwd 取最新互补〔07 §5〕）；
+ *    非 TTY 卫兵同 TUI 主入口律（管道/CI 退 2 指引改 run --session）。
+ *
+ * 退出码：0 成功（含空清单/零命中——诚实空非失败）/ 1 执行失败（会话不
+ * 存在、fork 否决、装配失败）/ 2 环境态误用（resume 非 TTY——07 §5 三态）。
+ */
+import { stdin as processStdin, stdout as processStdout, stderr as processStderr } from 'node:process';
+import { Persistence } from '../persist/index.js';
+import { assembleHostStack } from './assembly.js';
+import { HOST_MIGRATION_TAIL } from './runtime.js';
+import { runTuiEntry } from './tui-entry.js';
+/** sessions 子命令族主入口。返回进程退出码（0/1/2；用法错归解析层） */
+export async function runSessionsEntry(sub, options) {
+    switch (sub.sub) {
+        case 'list':
+            return runList(options);
+        case 'search':
+            return runSearch(options, sub.query);
+        case 'reindex':
+            return runReindex(options);
+        case 'resume':
+            return runResume(options, sub.id);
+        case 'fork':
+            return runFork(options, sub.id);
+    }
+}
+/* ---------------- 读腿基建（零装配直开库） ---------------- */
+/**
+ * 读腿/维护动词开库（宿主迁移链尾单源；库文件路径走三级梯子缺省——与一切
+ * 入口同库同律；warn 走错误面——毒丸/撕裂尾告警直达人面）。
+ */
+function openReadSide(options, err) {
+    return Persistence.open({
+        ...(options.dbPath !== undefined ? { dbPath: options.dbPath } : {}),
+        ...(options.dataDir !== undefined ? { dataDir: options.dataDir } : {}),
+        migrations: HOST_MIGRATION_TAIL,
+        warn: (message) => err(`warn：${message}`),
+    });
+}
+/** ISO 时间形态（ms epoch → 确定性串——测试可断言） */
+function isoOf(ms) {
+    return new Date(ms).toISOString();
+}
+/** 血缘形（origin + 父链箭头——统一式不逐 origin 造文案） */
+function lineageOf(origin, parentId) {
+    return parentId === undefined ? origin : `${origin}←${parentId}`;
+}
+/* ---------------- list ---------------- */
+/** list：会话清单（id/标题/时间/血缘；updated 倒序） */
+async function runList(options) {
+    const out = options.writeOut ?? ((text) => processStdout.write(`${text}\n`));
+    const err = options.writeErr ?? ((text) => processStderr.write(`${text}\n`));
+    const persistence = openReadSide(options, err);
+    try {
+        const rows = persistence.store.listSessions({ limit: 100 });
+        if (rows.length === 0) {
+            out('无会话（数据目录尚无在册会话——首跑 run/TUI 即建）');
+            return 0;
+        }
+        const lines = [`共 ${rows.length} 个会话（updated 倒序，帽 100）：`];
+        for (const row of rows) {
+            lines.push(`  ${row.id}  ${row.title ?? '（无标题）'}  创建 ${isoOf(row.createdAt)}  更新 ${isoOf(row.updatedAt)}  ${lineageOf(row.origin, row.parentId)}`);
+        }
+        out(lines.join('\n'));
+        return 0;
+    }
+    finally {
+        await persistence.close();
+    }
+}
+/* ---------------- search ---------------- */
+/** 命中行 snippet 切窗（首现位 ±30 字符；空白折叠单行——body 为索引投影原文，消费侧自切〔05 §9〕） */
+function snippetOf(body, query) {
+    const flat = body.replace(/\s+/g, ' ').trim();
+    const at = flat.toLowerCase().indexOf(query.toLowerCase());
+    if (at < 0)
+        return flat.length > 64 ? `${flat.slice(0, 64)}…` : flat; // trigram 归一后首现位缺席——退头窗
+    const start = Math.max(0, at - 30);
+    const end = Math.min(flat.length, at + query.length + 30);
+    return `${start > 0 ? '…' : ''}${flat.slice(start, end)}${end < flat.length ? '…' : ''}`;
+}
+/** search：跨会话 FTS 全文检索（bm25 序；输出 id/标题/命中行） */
+async function runSearch(options, query) {
+    const out = options.writeOut ?? ((text) => processStdout.write(`${text}\n`));
+    const err = options.writeErr ?? ((text) => processStderr.write(`${text}\n`));
+    const persistence = openReadSide(options, err);
+    try {
+        const hits = persistence.store.searchFtsGlobal(query, 50);
+        if (hits.length === 0) {
+            out(`无命中（${query}）`);
+            return 0;
+        }
+        // 标题面一次读齐（命中行带 session 归属——行面反查人读标题）
+        const titles = new Map();
+        for (const row of persistence.store.listSessions({ limit: 1000 })) {
+            titles.set(row.id, { title: row.title, origin: row.origin, parentId: row.parentId });
+        }
+        const lines = [`命中 ${hits.length} 处（bm25 序，帽 50）：`];
+        for (const hit of hits) {
+            const meta = titles.get(hit.sessionId);
+            const head = `${hit.sessionId}  ${meta?.title ?? '（无标题）'}`;
+            lines.push(`  ${head}  #${hit.seq}  ${snippetOf(hit.body, query)}`);
+        }
+        out(lines.join('\n'));
+        return 0;
+    }
+    finally {
+        await persistence.close();
+    }
+}
+/* ---------------- reindex ---------------- */
+/** reindex：FTS 全量重建（05 §9 托付的手动重建命令——诊断索引漂移后的一键复位；派生物不修不补） */
+async function runReindex(options) {
+    const out = options.writeOut ?? ((text) => processStdout.write(`${text}\n`));
+    const err = options.writeErr ?? ((text) => processStderr.write(`${text}\n`));
+    const persistence = openReadSide(options, err);
+    try {
+        const result = persistence.store.rebuildFts();
+        out(`FTS 重建完成：${result.sessions} 会话 / ${result.events} 事件入索引（派生物重建即修复）`);
+        return 0;
+    }
+    finally {
+        await persistence.close();
+    }
+}
+/* ---------------- resume（进 TUI） ---------------- */
+/** resume：按 id 续接后进 TUI（runTuiEntry resumeSessionId 载体；非 TTY 卫兵同 TUI 主入口律） */
+async function runResume(options, id) {
+    const err = options.writeErr ?? ((text) => processStderr.write(`${text}\n`));
+    const stdinIsTTY = options.stdinIsTTY ?? processStdin.isTTY === true;
+    const stdoutIsTTY = options.stdoutIsTTY ?? processStdout.isTTY === true;
+    if (!stdinIsTTY || !stdoutIsTTY) {
+        err('非交互环境（stdin/stdout 非 TTY）——sessions resume 进 TUI 不适用于管道/CI；单发续接改用 `berry-agent run --session <id> "<message>"`。');
+        return 2;
+    }
+    // 直托 TUI 主入口（装配序单源）：resumeSessionId 在场即按 id 续接，缺席
+    // 语义面归 tui-entry；id 打错的干净退 1 由其内呈报
+    const flags = { noPlugins: false, debug: false };
+    return runTuiEntry({
+        flags,
+        version: options.version,
+        ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+        ...(options.dataDir !== undefined ? { dataDir: options.dataDir } : {}),
+        ...(options.env !== undefined ? { env: options.env } : {}),
+        ...(options.providers !== undefined ? { providers: options.providers } : {}),
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        ...(options.sandboxMode !== undefined ? { sandboxMode: options.sandboxMode } : {}),
+        ...(options.io !== undefined ? { io: options.io } : {}),
+        ...(options.onRuntime !== undefined ? { onRuntime: options.onRuntime } : {}),
+        resumeSessionId: id,
+    });
+}
+/* ---------------- fork（全装配） ---------------- */
+/** fork：边界快照分叉（05 §5.0 机制单源在 SessionManager.fork；与 run --fork / TUI fork 同机——钩子保真 + 单活跃机占标记） */
+async function runFork(options, id) {
+    const out = options.writeOut ?? ((text) => processStdout.write(`${text}\n`));
+    const err = options.writeErr ?? ((text) => processStderr.write(`${text}\n`));
+    const assembly = await assembleHostStack({
+        runtime: {
+            ...(options.dataDir !== undefined ? { dataDir: options.dataDir } : {}),
+        },
+        noPlugins: false, // fork 与 TUI 同构装载面——session_before_fork 钩子（checkpoint gate 等）保真
+        debug: false,
+        version: options.version,
+        ...(options.env !== undefined ? { env: options.env } : {}),
+        ...(options.providers !== undefined ? { providers: options.providers } : {}),
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        ...(options.sandboxMode !== undefined ? { sandboxMode: options.sandboxMode } : {}),
+        ...(options.onRuntime !== undefined ? { onRuntime: options.onRuntime } : {}),
+    });
+    if (!assembly.ok) {
+        err(assembly.message); // 单活跃机/开库/启用清单损坏——干净退出档（不写 crash.log）
+        return assembly.exitCode;
+    }
+    try {
+        // 源存在性预检：manager.fork 的缺席 throw 是调用序 bug 面（PERSIST_DATA_
+        // CORRUPT）——CLI 人面把打错 id 呈报为干净失败档
+        const row = assembly.runtime.persistence.store.getSessionRow(id);
+        if (row === undefined) {
+            err(`会话不存在：${id}——用 sessions list 查在册 id`);
+            return 1;
+        }
+        let forked;
+        try {
+            forked = await assembly.stack.manager.fork(id);
+        }
+        catch (error) {
+            err(`fork 失败：${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+        if (forked.status === 'vetoed') {
+            // session_before_fork 钩子否决——非错误路径但 fork 无法进行（退 1 执行失败档）
+            err(`fork 被钩子否决：${forked.reason}`);
+            return 1;
+        }
+        out(`已分叉：${forked.sessionId}`);
+        out(`  源会话 ${id}（种子 ${forked.lineage.seedLength} 事件）`);
+        out(`  续接：berry-agent sessions resume ${forked.sessionId}`);
+        return 0;
+    }
+    finally {
+        await assembly.runtime.shutdown();
+    }
+}

package/dist/host/sessions-face.js

@@ -0,0 +1,47 @@
+/**
+ * 'sessions' 服务面（03 §4.4/§4.5 + 06 §318 appendEvent 最小面——批 19 销账笔）。
+ *
+ * 宿主装配根 provide 的活引用面：appendEventFor(sessionId) 按会话解析**当下**
+ * 活体驱动（/new 热切换安全 = 调用时点解析非装配期冻结）；无活体驱动 =
+ * undefined 降级（服务照常 provide——诚实缺席律：消费方〔core:memory 差分
+ * 落账腿〕捕获后自行降级，mirror 不锁步）。
+ *
+ * 二道闸（06 §318 定稿条款——闭环在闭包内非依赖 SessionLog 下游）：
+ *  ①核心事件词伪造拒写——核心词写入权属宿主（核心事件族 = 驱动单源）；
+ *  ②未注册词汇拒写——与 SessionLog.append 下游 SESSION_UNKNOWN_EVENT_TYPE
+ *    同判据（前置在此 = 错误信息可携带服务面上下文；下游仍兜底）。
+ *
+ * 完整 ctx.sessions 面（只读四件 + 受理制写两腿 + 三闸）归后续批——本件只落
+ * appendEvent 最小面（memory/diff 唯一 durable 出口的承载位）+ surfaceOp
+ * 信封参数腿（03 §4.5 修缝批 2026-09-08：受控注入原语可选信封位——改道
+ * appendWithSurfaceOp 正门，插件自定义压缩类操作的唯一合法投影写径）。
+ */
+import { BaseError, CORE_EVENT_TYPE_NAMES, isKnownEventType } from '../contracts/index.js';
+/** 建 sessions 服务面（装配根：`scope.provide('sessions', createSessionsFace({ driverOf }))`） */
+export function createSessionsFace(options) {
+    return {
+        appendEventFor(sessionId) {
+            const log = options.driverOf(sessionId)?.session;
+            if (log === undefined)
+                return undefined; // 无活体驱动——诚实缺席（不造回库替身）
+            return (type, data, surfaceOp, sourceEventSeqs) => {
+                // 闸一：核心事件词伪造拒写（核心词写入权属宿主——双入口纪律的受理侧）
+                if (CORE_EVENT_TYPE_NAMES.includes(type)) {
+                    throw new BaseError('SESSION_CORE_TYPE_FORBIDDEN', `核心事件词 ${type} 拒经 sessions.appendEventFor 写入（核心事件族写入权属宿主驱动单源——06 §6 二道闸①）`);
+                }
+                // 闸二：未注册词汇拒写（词汇注册表单源；判据与 SessionLog.append 下游同源）
+                if (!isKnownEventType(type)) {
+                    throw new BaseError('SESSION_UNKNOWN_EVENT_TYPE', `事件词 ${type} 未在词汇注册表（sessions.appendEventFor 前置闸——下游 SessionLog.append 同判据兜底）`);
+                }
+                // surfaceOp 信封参数腿（03 §4.5）：携带信封即改道 appendWithSurfaceOp
+                // 正门——一切改投影历史的唯一正门（05 §2.1）。边缘纪律五条与
+                // SESSION_SURFACE_OP_INVALID 由正门单点执法（受理面零第二校验面）；
+                // 二道闸对两路同前置（核心词携信封同拦——词面收窄注记的执法位）。
+                if (surfaceOp !== undefined) {
+                    return log.appendWithSurfaceOp(type, data, surfaceOp, sourceEventSeqs);
+                }
+                return log.append(type, data);
+            };
+        },
+    };
+}