berry-agent 0.1.0-alpha.1

package/dist/host/tool-policy-store.js

@@ -0,0 +1,177 @@
+/**
+ * host/tool-policy-store — 跨会话工具策略表文件读写件（04 §9 粘性第 3 款
+ * 2026-09-07 定形块的装配侧执法；批 12f-4；2026-09-11 审批分档批六字段行形
+ * 扩 + 载体更名 tool-policy.json——本件即更名执法与旧文件升格迁移所在）。
+ *
+ * 载体 = 数据目录 `tool-policy.json`（单一用途用户资产文件——与
+ * boot-failures/ledger 同族 JSON；原名 `allowlist.json`，本批更名）。本件只
+ * 管文件 IO 与行校验；匹配判定归 safety 域纯函数半边（matchToolPolicy——
+ * engine 不碰文件），草案生成归审批服务（suggestedEntry）。
+ *
+ * 新旧文件共存序（04 §9 定形块③）：**新文件在场即唯一源**（旧文件在场也
+ * 不读）；**唯旧在场且新缺席才升格读入**（旧三字段形 decision 缺席归一
+ * allow——ap-1 读侧归一语义）；**旧文件留置不删**（机器永不写入旧名——
+ * 升格只发生在读侧，新条目追加恒落新文件名；首次追加即把升格条目物化进
+ * 新文件，旧文件自此为惰性遗存。生态未启动实际零存量，防御性迁移）。
+ *
+ * 读写三律（定形块原文执法）：
+ * - 读侧装配期载入：缺席 = 空清单零负担；**文件级坏形 = warn 降级视同空
+ *   清单**（advisory 免问面坏形降级方向 = 更严〔多问〕不是更松，fail-closed
+ *   同向——与 enabled.yaml 拒启律分立）；**行级坏形 = 剔除该行 + warn 点名**
+ *   （防类型脏行进匹配引擎；含 deny 条目带 expiresAt 的方向性坏形；文件不
+ *   因读侧改写——机器永不覆写用户手写面）。升格读入语境下旧文件即当前
+ *   源——旧文件坏形同律（坏形期回写拒，修复归用户手面）。
+ * - 写侧唯一正门（装配注入 persistToolPolicy 回调）：**只产 allow 条目**
+ *   （deny 唯用户手写）；append 幂等去重（同 tool+pattern 不二写）+
+ *   **原子替换**（临时文件 + rename——防撕裂丢条目）；**坏形期回写拒**
+ *   （机器不在坏形文件上追加——防覆写扩大破坏，修复归用户手面）。
+ * - fence（§7/§8 carve-out）：本文件属数据目录族恒不可写——模型不可改自己
+ *   的免问面；本件写入只经装配层回调（用户显式按键触发），文件级只读校验
+ *   前置即坏形拒写的第一道闸。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** 策略表文件名（数据目录单段——04 §9 定形块③定名，2026-09-11 审批分档批更名） */
+export const TOOL_POLICY_BASENAME = 'tool-policy.json';
+/**
+ * 旧载体名（更名前遗留）——升格读入用，**本件永不写入此名**（旧文件留置
+ * 不删；读侧敏感件保护两名单同列——safety/sensitive 防旧文件读敞门）。
+ */
+export const LEGACY_ALLOWLIST_BASENAME = 'allowlist.json';
+/**
+ * 单文件解析 + 行级校验（新旧文件同律——升格语境下旧三字段形 decision 缺席
+ * 归一 allow）。返回 healthy=false = 文件级坏形（调用方定降级语义）。
+ */
+function loadPolicyFile(path, warn) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        warn(`策略表读取失败（${path}）：${err instanceof Error ? err.message : String(err)}——视同空清单`);
+        return { entries: [], healthy: false, unhealthyPath: path };
+    }
+    // 文件级三检：JSON 可解析 / 顶层对象 / entries 为数组——任一违例整文件降级
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch (err) {
+        warn(`策略表坏形（${path}，JSON 解析失败：${err instanceof Error ? err.message : String(err)}）——视同空清单；手改修复前回写拒（防机器覆写扩大破坏）`);
+        return { entries: [], healthy: false, unhealthyPath: path };
+    }
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+        warn(`策略表坏形（${path}，顶层须为对象 { "entries": [...] }）——视同空清单；手改修复前回写拒`);
+        return { entries: [], healthy: false, unhealthyPath: path };
+    }
+    const rows = doc.entries;
+    if (!Array.isArray(rows)) {
+        warn(`策略表坏形（${path}，entries 须为数组）——视同空清单；手改修复前回写拒`);
+        return { entries: [], healthy: false, unhealthyPath: path };
+    }
+    // 行级校验（拒绝式 schema——2026-09-11 审批分档批六字段扩：tool 非空字符串
+    // 必填、pattern 可选〔在场须为字符串——空串/缺席对整名族合法；fs/bash 族
+    // 条目缺席 = 引擎恒 miss 的惰性行，fail-closed 方向无害〕、decision 闭集
+    // 'allow'|'deny'〔缺席 = allow——旧三字段形升格读入语义〕、effect 闭集
+    // read|write|exec 可选、reason 可选字符串、expiresAt 可选数值〔**deny 条目带
+    // expiresAt = 坏形剔除**——deny 无 TTL，04 §9 定形块③方向性条款〕、未知键
+    // 拒）——违例剔行 warn 点名（文件不动：机器永不改写用户手写面）
+    const entries = [];
+    rows.forEach((row, index) => {
+        if (typeof row !== 'object' || row === null) {
+            warn(`策略表第 ${index + 1} 行非对象——剔除（文件未改动）`);
+            return;
+        }
+        const { tool, pattern, decision, effect, reason, expiresAt, ...rest } = row;
+        if (typeof tool !== 'string' || tool.length === 0) {
+            warn(`策略表第 ${index + 1} 行 tool 缺失或非字符串——剔除（文件未改动）`);
+            return;
+        }
+        if (pattern !== undefined && typeof pattern !== 'string') {
+            warn(`策略表第 ${index + 1} 行 pattern 须为字符串——剔除（文件未改动）`);
+            return;
+        }
+        if (decision !== undefined && decision !== 'allow' && decision !== 'deny') {
+            warn(`策略表第 ${index + 1} 行 decision 闭集外（allow|deny）——剔除（文件未改动）`);
+            return;
+        }
+        if (effect !== undefined && effect !== 'read' && effect !== 'write' && effect !== 'exec') {
+            warn(`策略表第 ${index + 1} 行 effect 闭集外（read|write|exec）——剔除（文件未改动）`);
+            return;
+        }
+        if (reason !== undefined && typeof reason !== 'string') {
+            warn(`策略表第 ${index + 1} 行 reason 须为字符串——剔除（文件未改动）`);
+            return;
+        }
+        if (expiresAt !== undefined && typeof expiresAt !== 'number') {
+            warn(`策略表第 ${index + 1} 行 expiresAt 须为数值——剔除（文件未改动）`);
+            return;
+        }
+        if (decision === 'deny' && expiresAt !== undefined) {
+            warn(`策略表第 ${index + 1} 行 deny 条目带 expiresAt 属坏形（deny 无 TTL——永久至手删）——剔除（文件未改动）`);
+            return;
+        }
+        const unknownKeys = Object.keys(rest);
+        if (unknownKeys.length > 0) {
+            warn(`策略表第 ${index + 1} 行未知键 ${unknownKeys.join('、')}——剔除（文件未改动）`);
+            return;
+        }
+        // 塑形落位：可选字段缺席即不带（JSON 面?键不落盘）；decision 缺席归一 allow
+        entries.push({
+            tool,
+            decision: decision ?? 'allow',
+            ...(pattern !== undefined ? { pattern } : {}),
+            ...(effect !== undefined ? { effect: effect } : {}),
+            ...(reason !== undefined ? { reason } : {}),
+            ...(expiresAt !== undefined ? { expiresAt } : {}),
+        });
+    });
+    return { entries, healthy: true };
+}
+/**
+ * 装配期载入工具策略表（04 §9 定形块读侧律 + 更名升格序）。新文件在场即
+ * 唯一源；唯旧在场且新缺席才升格读入（旧文件留置不删）；两文件皆缺席 =
+ * 空清单 healthy（零负担首启）；文件级坏形 = 空 + warn + unhealthy；行级
+ * 坏形 = 剔行 + warn 点名。
+ */
+export function readToolPolicy(dataDir, options = {}) {
+    const warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    // 共存优先序：新名在场即唯一源（旧名在场也不读——防止双源漂移）
+    const path = join(dataDir, TOOL_POLICY_BASENAME);
+    if (existsSync(path))
+        return loadPolicyFile(path, warn);
+    // 升格读入：唯旧在场且新缺席——旧三字段形经行级归一（decision 缺省 allow）
+    const legacyPath = join(dataDir, LEGACY_ALLOWLIST_BASENAME);
+    if (existsSync(legacyPath)) {
+        warn(`allowlist.json 已更名 tool-policy.json（2026-09-11 审批分档批）——旧文件条目升格读入，旧文件留置不动（机器永不写旧名；新条目追加落新文件 ${TOOL_POLICY_BASENAME}）`);
+        return loadPolicyFile(legacyPath, warn);
+    }
+    return { entries: [], healthy: true };
+}
+/**
+ * 写侧唯一正门：追加 **allow 条目**（04 §9 定形块写侧律 + 审批分档批③——
+ * 机器永不写 deny，deny 是用户主权面唯用户手写）。幂等去重（同 tool+pattern
+ * 的 allow 条目不二写——手写 deny 条目不参与去重键：引擎 deny 优先律下机器
+ * allow 追加恒 inert，但去重误报 duplicate 会吞掉用户按键的真实意图呈现）；
+ * 原子替换落盘（tmp + rename）；文件级坏形期拒写（修复归用户手面——升格
+ * 语境下旧文件坏形同拒）。写入恒落新名 tool-policy.json（升格条目随首次
+ * 追加物化进新文件，旧文件自此为惰性遗存）。
+ */
+export function appendToolPolicyEntry(dataDir, draft) {
+    const path = join(dataDir, TOOL_POLICY_BASENAME);
+    // 坏形拒写第一闸：复用读侧全套校验（坏形期在坏文件上追加 = 覆写扩大破坏）
+    const load = readToolPolicy(dataDir);
+    if (!load.healthy)
+        return 'rejected';
+    if (load.entries.some((e) => e.decision !== 'deny' && e.tool === draft.tool && e.pattern === draft.pattern)) {
+        return 'duplicate';
+    }
+    // 机器写入恒带 decision:'allow'（正门只产 allow 条目——六字段形自证）
+    const entries = [...load.entries, { tool: draft.tool, pattern: draft.pattern, decision: 'allow' }];
+    // 原子替换：临时文件写全量后 rename——撕裂窗口不暴露半文件（用户资产完整性）
+    mkdirSync(dataDir, { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify({ entries }, null, 2)}\n`, 'utf8');
+    renameSync(tmp, path);
+    return 'appended';
+}

package/dist/host/triggers.js

@@ -0,0 +1,212 @@
+/**
+ * host/triggers — 触发器注册面（03 §2.2 行 108 ctx.triggers.register 第十一动词
+ * + §2.7 触发器行冲突律 + §4.6 开门制；2026-09-07 触发器面 C 批 C-2 注册面笔
+ * + C-3 starter 笔）。
+ *
+ * 一件三面：
+ *  - **注册表本体**（单实例随装配根创建；插件经 ctx.triggers.register 间接消费
+ *    ——窗口/频率护栏在 ctx 面执法，本件只管三闸与 starter 交接）：
+ *    闸一 门检（`triggers.start-run` 高危面默认关——03 §4.6；core: 官方件直开
+ *    豁免〔装配即用户意图，§4.6 勘补判据——官方件随构建进包非生态授予面〕；
+ *    开门授予集经 `getOpens` **活体读取源**现取现判——与 fire 复检同源，
+ *    /reload 撤位后旧 starter 复检即拒，开门可收回）；
+ *    闸二 撞名（TRIGGER_NAME_EXISTS——词法身份面拒绝式，重影即审计归因歧义；
+ *    先于格式闸，「名字被占用」比「格式违例」更指向根因，registerMessageRole
+ *    同序）；
+ *    闸三 名词法（TRIGGER_NAME_INVALID——域名两段式〔恰含一个 /、两段均小写
+ *    字母数字连字符〕且域前缀 == 本插件 id，core: 件去前缀取 name 段比对
+ *    ——防跨插件冒名，registerSection 同法）。
+ *  - **starter 一次性交接**：注册成功即回调 `def.fire(starter)` 注入起会闭包
+ *    （03 §2.2 行 108 定形注记——重装载经重注册重新注入，旧 starter 因 fire
+ *    复检悬空失效不悬空越权）。
+ *  - **starter 真身工厂**（createTriggerStarterFactory——装配根注入窄依赖面
+ *    造 `(pluginId, name) => starter`）：fire 复检（活体开门收回）→ Job 受理
+ *    **先于**起会（「fire 受理先过帽再起会话」——帽满 JOB_LIMIT_REACHED /
+ *    显式 jobKind 未登记 JOB_KIND_UNKNOWN，不起会不留孤儿）→ 起无头会话
+ *    （origin 'trigger' + source `plugin:<id>` 归因 + per-fresh-session 模型
+ *    载体）→ 回执三终态映射 Job 终态（completed→completed / aborted→killed /
+ *    failed→failed；injected/wake-refused = run 未起落 failed）。**starter
+ *    永不 throw**——插件事件源回调内执行，throw 即进程级风险；拒与失败一律
+ *    warn 可观测 + Job 终态收口（无人值守鲁棒性）。
+ *
+ * 审计实况（2026-09-11 勘正——原注两处挂账均已飞）：capability/used 逐次
+ * 审计已随 U3 落码批接线（audit_events 载体在场——assembly createAuditFace
+ * 单写者；v1 归因面另经事件流 source=`plugin:<id>` 闭集可查——03 §2.2 行 108
+ * 定形注记）；JobHandle.stop→interrupt 桥接与插件卸载 closeOwner(pluginId)
+ * 收口均已随 Job 消费面批兑现（04 §10 定形：onStop 协作中止路由 + 卸载接线位
+ * = plugin-unload closer——本文件两桥腿 = starter 注册 onStop 路由到起会
+ * 驱动 abort；closeOwner 接线在 plugin-boot 装配件）。
+ */
+import { BaseError } from '../contracts/index.js';
+// internal 桶机制符号深导（门检裁决核——03 §4.6；开门是宿主裁决面非插件 API）
+import { adjudicateCapabilityDoor } from '../contracts/api.js';
+/** 触发器名词法（域名两段式——两段均小写字母起头的小写字母数字连字符串，messages CUSTOM_ROLE_RE 同法） */
+const TRIGGER_NAME_RE = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/;
+/** 域前缀归一（core: 件去前缀取 name 段比对——prompt-sections domainOf 同法） */
+function domainOf(pluginId) {
+    return pluginId.startsWith('core:') ? (pluginId.slice('core:'.length) ?? pluginId) : pluginId;
+}
+/**
+ * 触发器注册表（单实例随装配根创建；core: 域与生态域同册——跨插件撞名互斥，
+ * 防官方件与生态插件同域重影）。零半注册残留：三闸全过才落册，fire 抛错回滚。
+ */
+export class TriggerRegistry {
+    options;
+    /** 触发器名 → 条目（枚举序 = 注册序——Map 插入序） */
+    triggers = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * 注册触发器（拒绝式三闸：门检 → 撞名 → 格式）。
+     * @returns 注销器（只摘本人条目——重注后旧注销器不误摘接任者）
+     */
+    register(pluginId, def) {
+        // 闸一：高危面门检（03 §4.6——triggers.start-run 默认关；授予集活体现判，
+        // 与 fire 复检同源开门可收回）。core: 官方件直开豁免——装配即用户意图
+        if (!pluginId.startsWith('core:')) {
+            const verdict = adjudicateCapabilityDoor(this.options.getOpens(pluginId), 'triggers.start-run');
+            if (!verdict.ok) {
+                throw new BaseError('PLUGIN_CAPABILITY_DOOR_CLOSED', `${verdict.message}（插件 ${pluginId}）`);
+            }
+        }
+        // 闸二：撞名（先于格式闸——在册名必已合法，「名字被占用」更指向根因）
+        const existing = this.triggers.get(def.name);
+        if (existing !== undefined) {
+            throw new BaseError('TRIGGER_NAME_EXISTS', `触发器 ${def.name} 已在册（注册方 ${existing.owner}）——词法身份面拒绝式，重影即审计归因歧义（03 §2.7）`);
+        }
+        // 闸三：名词法（域名两段式 + 域前缀 == 本插件 id——core: 件去前缀比对）
+        const slash = def.name.indexOf('/');
+        if (!TRIGGER_NAME_RE.test(def.name) || slash <= 0 || def.name.slice(0, slash) !== domainOf(pluginId)) {
+            throw new BaseError('TRIGGER_NAME_INVALID', `触发器名 ${def.name} 非域名两段式或域前缀 ≠ 本插件 id（须 ${domainOf(pluginId)}/名——恰含一个 / 且两段均小写字母数字连字符；core: 件去前缀取 name 段比对——防跨插件冒名，03 §2.7）`);
+        }
+        const entry = { name: def.name, owner: pluginId, description: def.description };
+        this.triggers.set(def.name, entry);
+        // 注册成功即一次性交接 starter（重装载经重注册重新注入；旧 starter 因 fire
+        // 复检悬空失效）。fire 抛错 = 注册未完成：回滚在册面再传播（装载器归
+        // PLUGIN_APPLY_FAILED 处置，零半注册残留）
+        try {
+            def.fire(this.options.makeStarter(pluginId, def.name));
+        }
+        catch (err) {
+            this.triggers.delete(def.name);
+            throw err;
+        }
+        return () => {
+            // 注销器只摘本人条目（防过期时序误摘接任者——registerMessageRole 同守卫）
+            if (this.triggers.get(def.name) === entry)
+                this.triggers.delete(def.name);
+        };
+    }
+    /** 在册名单快照（枚举序 = 注册序——测试/审计读侧） */
+    list() {
+        return [...this.triggers.values()];
+    }
+}
+/* ---------------- starter 真身（C-3 装配批——起无头会话 + Job 托管编舞） ---------------- */
+/** trigger kind 缺省并行帽（03 §2.2 行 108 定形注记——host 装配期自登 kind + 帽 4） */
+export const TRIGGER_JOB_PARALLEL_LIMIT = 4;
+/**
+ * starter 真身工厂（装配根消费——TriggerRegistry makeStarter 位注入）。
+ *
+ * 编舞序（受理先行的对称收口——任何一步失败都让 Job 落终态，不留 running
+ * 悬空条目）：fire 复检（core: 豁免，拒 = warn + return）→ spec 轻校验 →
+ * Job 受理（先过帽再起会）→ 起会（origin 'trigger'）→ 提交（source
+ * `plugin:<id>`）→ 回执三终态映射 Job 终态。回执腿 fire-and-forget：starter
+ * 同步返回，run 终态经 JobSettledEvent 活体通知可观测。
+ */
+export function createTriggerStarterFactory(deps) {
+    return (pluginId, name) => (spec) => {
+        // —— fire 复检（03 §4.6 开门可收回）：与注册闸同源活体判——/reload 撤位后
+        // 旧 starter 现判现拒；core: 官方件直开豁免（同注册闸判据）
+        if (!pluginId.startsWith('core:')) {
+            const verdict = adjudicateCapabilityDoor(deps.getOpens(pluginId), 'triggers.start-run');
+            if (!verdict.ok) {
+                deps.warn(`触发器 ${name} 起会被拒：${verdict.message}（插件 ${pluginId}——fire 复检，开门可收回）`);
+                return;
+            }
+        }
+        // —— spec 轻校验（插件代码运行期传参防御——TS 形状之外的运行时防线）
+        if (typeof spec.prompt !== 'string' || spec.prompt.length === 0) {
+            deps.warn(`触发器 ${name} 起会参数坏形：prompt 缺席或空（插件 ${pluginId}）`);
+            return;
+        }
+        // —— Job 受理先于起会（「fire 受理先过帽再起会话」：帽满 JOB_LIMIT_REACHED /
+        // 显式 jobKind 未登记 JOB_KIND_UNKNOWN 都不造孤儿会话）。owner = 插件 id
+        // 围栏键（插件卸载 closeOwner(pluginId) 收口——Job 消费面批接线
+        // plugin-unload closer）。onStop 协作中止路由（Job 消费面批两桥之一）：
+        // stop/closeOwner 置 stopping 后路由到起会驱动的 abort——run 协作中止
+        // （aborted 回执 settle killed 与收口兜底 first-wins 竞速，先落者胜）；
+        // opened 闭包晚绑（受理先于起会——路由时 opened 必已赋值，防御判空
+        // 覆盖 create 抛错后的悬空路由形）
+        const title = spec.title ?? `${name} ${new Date().toISOString()}`;
+        let opened;
+        let job;
+        try {
+            job = deps.jobs.register({
+                kind: spec.jobKind ?? 'trigger',
+                name: title,
+                owner: pluginId,
+                onStop: () => {
+                    opened?.driver.abort();
+                },
+            });
+        }
+        catch (err) {
+            deps.warn(`触发器 ${name} Job 受理失败（插件 ${pluginId}）：${err instanceof BaseError ? `[${err.code}] ${err.message}` : String(err)}`);
+            return;
+        }
+        // —— 起无头会话（origin 'trigger'；model 纯内存 per-fresh-session 载体）
+        try {
+            opened = deps.stack.manager.create({
+                origin: 'trigger',
+                workspaceRoot: deps.workspaceRoot(),
+                title,
+                ...(spec.model !== undefined ? { model: spec.model } : {}),
+            });
+        }
+        catch (err) {
+            const detail = `起会失败：${err instanceof Error ? err.message : String(err)}`;
+            job.settle({ status: 'failed', detail });
+            deps.warn(`触发器 ${name} 起会失败（插件 ${pluginId}）：${detail}`);
+            return;
+        }
+        // —— 提交首条输入（source=`plugin:<id>` 归因——05 §3.1 受控注入位）
+        const submitted = deps.stack.submitText(opened.sessionId, spec.prompt, { source: `plugin:${pluginId}` });
+        if (submitted === undefined) {
+            job.settle({ status: 'failed', detail: 'run 未起——会话驱动缺席' });
+            deps.warn(`触发器 ${name} 提交失败：会话驱动缺席（插件 ${pluginId}）`);
+            return;
+        }
+        // —— capability/used 逐次落账（05 §1.1——triggers.start-run 腿，C 批挂账
+        // U3-5 兑现）：run 真起才算使用；core: 豁免门检照记（豁免免的是门不是账）
+        deps.onCapabilityUsed?.(pluginId, name);
+        // —— 回执 → Job 终态映射（aborted→killed 承 Job 终态词——SubagentStopReason
+        // 同映射；injected/wake-refused 两收执 = run 未起，落 failed 交代去向）
+        void submitted.then((result) => {
+            if (result.status === 'completed') {
+                job.settle({ status: 'completed' });
+            }
+            else if (result.status === 'aborted') {
+                job.settle({ status: 'killed', detail: 'run 被中止' });
+            }
+            else if (result.status === 'failed') {
+                job.settle({
+                    status: 'failed',
+                    ...(result.errorMessage !== undefined ? { detail: result.errorMessage } : {}),
+                });
+            }
+            else if (result.status === 'injected') {
+                job.settle({
+                    status: 'failed',
+                    detail: `run 未起——输入落 inject 通道（durable seq ${result.seq}，随下次启动带入）`,
+                });
+            }
+            else {
+                job.settle({ status: 'failed', detail: 'run 未起——连续后台唤醒超帽拒收（wake-refused）' });
+            }
+        }, (err) => {
+            job.settle({ status: 'failed', detail: `run 异常：${err instanceof Error ? err.message : String(err)}` });
+        });
+    };
+}

package/dist/host/tui-entry.js

@@ -0,0 +1,216 @@
+/**
+ * host/tui-entry — TUI 主入口装配（批 12e；07 §5 无参启动 = TUI 主入口）。
+ *
+ * 装配序（channels/service.ts 头注真源；公共段批 12f-3 抽 assembly.ts——与
+ * dump-config/plugins list 诊断命令同一合成代码路径）：assembleHostStack
+ * （运行时→logger→根作用域/总线→conversation 栈→插件装载，:memory: 同构
+ * 纪律防侧门件）→ [本件 TUI 段] --port webui 开面（装载后/挂接前）→
+ * openStartupSession（07 §5 启动会话策略：cwd 归一根取最新续接、无则新建；
+ * resumeSessionId 在场 = 按 id 续接——sessions resume <id> 的 CLI 载体〔批 20d〕）
+ * → TuiBackend 组装（提交/打断/退出/命令分发/todo 回看/补全三源/version
+ * 基线/生产定时器）→ addBackend → start → registerSession → focus 首画 →
+ * 主循环 await 退出 → runtime.shutdown 六步退出序（closer 内含 backend.stop
+ * 出屏复原）。
+ *
+ * 退出码：0 = ctrl+d 空框优雅退出；1 = 运行时组装失败（单活跃机拒入/开库
+ * 失败——干净退出不写 crash.log，非崩溃）、启用清单损坏（同干净退出档）或
+ * 运行期异常（先 writeCrashLog 再退）。
+ * 信号路径独立：SIGINT①/SIGTERM → onGraceful → runtime.shutdown → exit(0)
+ * （main.ts 编舞；本件 closer 注册保证出屏复原在该路径同样执行）。
+ */
+import { FileMentionSource, ProcessTerminalIO, TuiBackend } from '../channels/index.js';
+import { canonicalWorkspaceRoot } from '../context/index.js';
+import { foldTodoTable } from '../conversation/index.js';
+import { sanitizeEntryForReadout } from '../memory/index.js';
+import { assembleHostStack } from './assembly.js';
+import { startSchedulerClock } from './core-plugins.js';
+import { runWithSessionAnchor } from './session-anchor.js';
+import { openWebuiFace } from './webui-bridge.js';
+/**
+ * TUI 主入口。阻塞至用户退出（ctrl+d 空框）或异常；返回进程退出码。
+ */
+export async function runTuiEntry(options) {
+    // —— 装配序公共段（12f-3 抽件）：与 dump-config/plugins list 诊断命令同一
+    // 合成代码路径（07 §5 :memory: 同构纪律——防侧门件 assembly.ts 唯一真源）；
+    // TUI 形 = 真数据目录 + 真库（memory 组合形归诊断命令）——
+    const assembly = await assembleHostStack({
+        runtime: {
+            ...(options.dataDir !== undefined ? { dataDir: options.dataDir } : {}),
+            ...(options.memory === true ? { memory: true } : {}),
+        },
+        noPlugins: options.flags.noPlugins === true,
+        // 快速试件透传（--plugin-file——03 §7 生态启动批 eco-3a；缺席形省键）
+        ...(options.flags.pluginFile !== undefined ? { pluginFile: options.flags.pluginFile } : {}),
+        debug: options.flags.debug === true,
+        version: options.version ?? '0.0.0',
+        ...(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.corePlugins !== undefined ? { corePlugins: options.corePlugins } : {}),
+        ...(options.onRuntime !== undefined ? { onRuntime: options.onRuntime } : {}),
+    });
+    if (!assembly.ok) {
+        // 两档呈报：crashed = 意外异常（crash.log 已在装配件内写——memory 形跳过）；
+        // 干净退出档 = 启动失败（单活跃机/开库/启用清单损坏——不写 crash.log）
+        process.stderr.write(`${assembly.crashed ? `TUI 运行失败：${assembly.message}` : assembly.message}\n`);
+        return assembly.exitCode;
+    }
+    const { runtime, stack, scope } = assembly;
+    let exitCode = 0;
+    try {
+        // —— scheduler 挂钟起钟（批 20c——长驻形编舞）：件在场即起（重启补推进
+        // + 排首轮轮询），停钟挂 closer（engine 真身定时器非 unref——不挂停钟
+        // 会把进程拖活到 60s belt 定时器）；件缺席 = no-op（件禁用语义族）——
+        startSchedulerClock(scope, runtime);
+        // —— --port webui 统一 HTTP 面开面（批 12f-2c 落、18a-3' 三入口咬合；
+        // 03 §10.4 host 接线）：装载后开面（插件注册面先就位）、TUI 挂接前开
+        // 网络面（closer 注册序先于 tui-backend——drain 时网络面先收口再出屏）；
+        // backend 挂接在桥共用挂载段内完成（与 TuiBackend 并存扇出——多 backend
+        // 信封路由按 sessionId 各投各）；横幅在 TUI 起屏后补发（开面时 backends
+        // 尚空 notify 扇出无人接帧——见下方 focus 后发）。批 19e 件在场执法：
+        // sdk 件缺席 = 面本体件禁用语义族——warn 一行不开面（TUI 屏本体不受
+        // 累）；webui 件缺席 = 面开而 /api/* 404（mountKit 缺席形——openWebuiFace
+        // 内分档披露，横幅同步分档）——
+        let webuiOpen;
+        let webuiMounted = false;
+        if (options.flags.port !== undefined) {
+            const sdkKit = scope.tryGet('sdk-http-face');
+            if (sdkKit === undefined) {
+                process.stderr.write('warn：core:sdk 件未装载——--port 人面不开（07 §5 daemon 拒启同族；TUI 屏不受累）\n');
+            }
+            else {
+                const mountKit = scope.tryGet('webui-face-mount');
+                webuiMounted = mountKit !== undefined;
+                await openWebuiFace({
+                    stack,
+                    runtime,
+                    port: options.flags.port,
+                    ...(mountKit !== undefined ? { mountKit } : {}),
+                    // U5-2：插件道路由受理器经 core:sdk kit 透传（snapshot/attachFace）
+                    ...(sdkKit.pluginRoutes !== undefined ? { pluginRoutes: sdkKit.pluginRoutes } : {}),
+                    onOpen: (info) => {
+                        webuiOpen = info;
+                        options.onWebuiOpen?.(info);
+                    },
+                });
+            }
+        }
+        // 启动会话策略（07 §5）：无参启动按 cwd 取最新会话——有则续接无则新建；
+        // resumeSessionId 在场（sessions resume <id> 的 CLI 载体）= 按 id 续接
+        // （与「按 cwd 取最新」互补）——id 缺席干净退 1（打错 id 不造新会话、不
+        // 写 crash.log；finally 仍走 shutdown 六步收口，此点尚未起 TUI 屏）
+        let session;
+        if (options.resumeSessionId !== undefined) {
+            let opened;
+            try {
+                opened = stack.manager.open(options.resumeSessionId);
+            }
+            catch {
+                process.stderr.write(`sessions resume 失败：会话不存在（${options.resumeSessionId}）——用 sessions list 查在册 id\n`);
+                return 1;
+            }
+            // @ 文件补全锚 = 会话自身工作区根（行面现读；缺席回退启动 cwd）
+            const row = runtime.persistence.store.getSessionRow(options.resumeSessionId);
+            session = {
+                sessionId: opened.sessionId,
+                driver: opened.driver,
+                resumed: true,
+                workspaceRoot: canonicalWorkspaceRoot(row?.workspaceRoot ?? options.cwd ?? process.cwd()),
+            };
+        }
+        else {
+            session = stack.openStartupSession(options.cwd ?? process.cwd());
+        }
+        const io = options.io ?? new ProcessTerminalIO();
+        let quitResolve = () => { };
+        const quitDone = new Promise((resolve) => {
+            quitResolve = resolve;
+        });
+        // 补全命令源：通道核命令表 → '/' 前缀条目（@ 文件段源锚工作区根）
+        const mentions = new FileMentionSource({ basePath: session.workspaceRoot });
+        const rows = io.size().rows;
+        const backend = new TuiBackend(io, {
+            sessionId: session.sessionId,
+            onSubmit: (sessionId, text) => {
+                void stack.submitText(sessionId, text); // fire-and-forget——回执经信封回流
+            },
+            onInterrupt: (sessionId) => stack.interrupt(sessionId),
+            onQuit: () => quitResolve(),
+            // 命令执行窗自动锚（ix-2——07 §4.3 档位 2）：发起会话 = 聚焦会话
+            //（兜底启动会话——焦点空悬时命令仍属 TUI 主会话）；ALS 语境继承语义
+            //——命令 handler 及其 fire-and-forget 尾链零自觉锚定（显式 opts
+            // .sessionId 优先）。sessionId 实参同笔透传（CommandArgs 显式位）。
+            dispatchCommand: (input) => {
+                const sid = stack.channels.focusedId ?? session.sessionId;
+                return runWithSessionAnchor(sid, () => stack.channels.dispatchCommand(input, sid));
+            },
+            todoFor: (sessionId) => {
+                const driver = stack.driverOf(sessionId);
+                return driver === undefined ? null : foldTodoTable(driver.session.events());
+            },
+            autocomplete: {
+                commands: (query) => commandItems(stack.channels.listCommands(), query),
+                mentions: (query) => mentions.get(query),
+            },
+            // 装配实测定值（07 §4.1）：编辑器可视行 = 终端高 30%（下钳 3）
+            maxVisibleLines: Math.max(3, Math.floor(rows * 0.3)),
+            ...(options.version !== undefined ? { version: options.version } : {}),
+            // 生产定时器注入（保活/帧帽真定时——缺省同步直出仅测试语义）
+            schedule: (fn, ms) => setTimeout(fn, ms),
+            cancelSchedule: (handle) => clearTimeout(handle),
+        });
+        // 出屏复原进退出序 closer——quit 路径与信号路径（onGraceful→shutdown）同享
+        runtime.registerCloser({ label: 'tui-backend', fn: () => backend.stop() });
+        // —— /memory 管理面材料注入（mm 批——06 §7 形态定形注）：boot 已完成
+        //（assembleHostStack 内插件装载），core:memory 服务面在场（库座在位且件
+        // 装载）→ 后置注入 TuiBackend 后置位：ownerKeys/runExport 经服务面传真
+        // 身（导出闭包 = /memory 命令注册同一形），消毒函数直取 §8.2 统一函数
+        // 本尊（「同一函数」由装配保证——channels 侧窄面结构兼容 MemoryDao）。
+        // 件缺席 = 不注入（openMemory 返 false——/memory 命令核侧 notify 降级）
+        const memoryFace = scope.tryGet('memory');
+        if (memoryFace !== undefined) {
+            backend.setMemoryScreen({
+                ownerKeys: memoryFace.ownerKeys,
+                dao: memoryFace.dao,
+                sanitize: sanitizeEntryForReadout,
+                exportCommand: memoryFace.runExport,
+            });
+        }
+        stack.channels.addBackend(backend);
+        backend.start();
+        stack.channels.registerSession(session.sessionId);
+        await stack.channels.focus(session.sessionId); // 启动投影首画（含 resume 历史回读）
+        // webui 开面横幅（18a-3'）：TuiBackend 起屏后经 channels.notify 扇出——
+        // notify 恒扇出（webui backend 同帧收到，浏览器通知位随活）；横幅走屏
+        // 留痕面只带 URL，token 不入屏（令牌仅 stderr 一次性——屏流可回滚/截屏，
+        // 非披露通道）；批 19e 分档：webui 件缺席形面仍开（SDK 面）——横幅诚实
+        // 报 HTTP 面形不虚报 Web 界面
+        if (webuiOpen !== undefined && webuiMounted) {
+            stack.channels.notify(session.sessionId, `Web 界面已开面：http://${webuiOpen.host}:${webuiOpen.port}/（访问令牌见启动 stderr——仅此一次显示）`, { level: 'info' });
+        }
+        else if (webuiOpen !== undefined) {
+            stack.channels.notify(session.sessionId, `HTTP 面已开面：http://${webuiOpen.host}:${webuiOpen.port}/（webui 件未装载——/v1/* 程序调用面在场，/api/* 404）`, { level: 'info' });
+        }
+        await quitDone; // 主循环——输入事件驱动，直至 ctrl+d 空框退出
+    }
+    catch (err) {
+        runtime.writeCrashLog(err); // 崩溃取证先行（memory 形跳过——件内语义）
+        process.stderr.write(`TUI 运行失败：${err instanceof Error ? err.message : String(err)}\n`);
+        exitCode = 1;
+    }
+    finally {
+        await runtime.shutdown(); // 幂等六步：abort → closer（backend.stop 出屏）→ flush → …
+    }
+    return exitCode;
+}
+/** 命令表 → 补全条目（'/' 前缀过滤——query 已去斜杠，AutocompleteSources 契约） */
+function commandItems(specs, query) {
+    return specs
+        .filter((spec) => spec.name.startsWith(query))
+        .map((spec) => ({
+        label: `/${spec.name}`,
+        ...(spec.description !== undefined ? { detail: spec.description } : {}),
+        replacement: `/${spec.name}`,
+    }));
+}