berry-agent 0.1.0-alpha.1

package/dist/context/events.js

@@ -0,0 +1,160 @@
+/**
+ * 事件分派四模式（04 §6「作用域与事件四模式」后半——分派契约）。
+ *
+ * 四模式（模式是事件契约的一部分）：
+ *  - emit：广播——全部监听器各跑各，异常互相隔离（单腿炸不波及他腿与调用方）；
+ *  - waterfall：串行管线——监听器必须调 next() 委托、不调即短路（管线后段
+ *    不再执行；守门行语义依赖它）；异常沿链传播（管线失败）；
+ *  - parallel：全体并发，Promise.all 收口（异常传播）；
+ *  - serial：排队串行（不短路，与 waterfall 的区别 = 无委托链）；异常隔离
+ *    不停后段（上报后继续）。
+ *
+ * 词汇纪律：自定义事件名走域名前缀（件/插件域）；未注册词 emit/on 均
+ * fail-loud（EVENT_NOT_REGISTERED）、撞名 EVENT_DUPLICATE 拒静默覆盖。
+ */
+import { BaseError } from '../contracts/index.js';
+/**
+ * 事件分派器：词汇注册表 + 四模式派发。一个 ctx 一枚（装载运行时的通信契约
+ * 单源——双实现 = 通信割裂）。
+ */
+export class EventDispatch {
+    /** 词汇注册表（name → 已注册标记；单源执法面） */
+    registered = new Set();
+    /** 监听器表（name → 注册序监听器列表；on 返回退订闭包；泛型在存储侧擦除为 unknown、取回侧 cast 还原） */
+    listeners = new Map();
+    /** serial 排队尾（per-name 链式 promise——排队串行） */
+    serialQueues = new Map();
+    /** 隔离腿异常上报（缺省 stderr 直写；装配根接 logger） */
+    onListenerError;
+    constructor(options) {
+        this.onListenerError =
+            options?.onListenerError ??
+                ((eventName, err) => {
+                    // 缺省面：stderr 直写（context 自身的 logger 尚未装配——先有鸡问题）
+                    console.error(`[context] 事件监听器异常（${eventName}）`, err);
+                });
+    }
+    /** 注册事件词汇（装载期声明面）；撞名拒 EVENT_DUPLICATE（禁静默覆盖） */
+    registerEventNames(names) {
+        for (const name of names) {
+            if (this.registered.has(name)) {
+                throw new BaseError('EVENT_DUPLICATE', `事件词汇 ${name} 已注册——拒静默覆盖（词汇注册表单源）`);
+            }
+            this.registered.add(name);
+        }
+    }
+    /** 判别词汇是否已注册（装配断言/诊断面） */
+    isRegistered(name) {
+        return this.registered.has(name);
+    }
+    /**
+     * 挂通知型监听器（emit/serial 共用监听面——同词两模式收同一监听器形态）。
+     * 词未注册拒 EVENT_NOT_REGISTERED（fail-loud 禁散播未声明事件名）。
+     * @returns 退订闭包（消费方经 scope.effect 组合生命周期）
+     */
+    on(name, listener) {
+        this.assertRegistered(name);
+        const list = this.listeners.get(name) ?? [];
+        const entry = { notify: listener };
+        list.push(entry);
+        this.listeners.set(name, list);
+        return () => {
+            const current = this.listeners.get(name);
+            if (!current)
+                return;
+            const idx = current.indexOf(entry);
+            if (idx >= 0)
+                current.splice(idx, 1);
+        };
+    }
+    /**
+     * 广播：全部监听器并发各跑各，异常互相隔离（单腿炸不波及他腿与调用方——
+     * 上报 onListenerError 后照常收口）。
+     */
+    async emit(name, data) {
+        this.assertRegistered(name);
+        const legs = (this.listeners.get(name) ?? []).map((entry) => entry.notify);
+        await Promise.all(legs.map(async (listener) => {
+            try {
+                await listener?.(data);
+            }
+            catch (err) {
+                this.onListenerError(name, err);
+            }
+        }));
+    }
+    /**
+     * 串行管线：监听器必须调 next(value) 委托——不调即短路（管线后段不再执行，
+     * 返回值为该监听器的产出）；异常沿链传播（管线失败语义——守门行依赖）。
+     */
+    async waterfall(name, value) {
+        this.assertRegistered(name);
+        // 存储侧泛型擦除为 unknown——取回 cast 还原为本次调用的 T（注册/派发两侧的
+        // 类型对齐由调用方契约保证，这里只做类型往返）
+        const chain = (this.listeners.get(name) ?? []).map((entry) => entry.waterfall).filter(Boolean);
+        // 自尾向头组合：每层 next 即下一段；尾 = 直通（value 原样出管线）
+        let next = (v) => Promise.resolve(v);
+        for (const listener of chain.reverse()) {
+            const downstream = next;
+            next = (v) => Promise.resolve(listener(v, downstream));
+        }
+        return next(value);
+    }
+    /** 挂管线监听器（waterfall 专用面——与 on 分开：形态不同防误用） */
+    onWaterfall(name, listener) {
+        this.assertRegistered(name);
+        const list = this.listeners.get(name) ?? [];
+        const entry = { waterfall: listener };
+        list.push(entry);
+        this.listeners.set(name, list);
+        return () => {
+            const current = this.listeners.get(name);
+            if (!current)
+                return;
+            const idx = current.indexOf(entry);
+            if (idx >= 0)
+                current.splice(idx, 1);
+        };
+    }
+    /**
+     * 全体并发，Promise.all 收口（异常传播——与 emit 的区别即异常语义）。
+     * 监听器面与 on 共用（通知型返回值参与收口）。
+     */
+    async parallel(name, data) {
+        this.assertRegistered(name);
+        const legs = (this.listeners.get(name) ?? []).map((entry) => entry.notify);
+        const results = await Promise.all(legs.map((listener) => Promise.resolve(listener ? listener(data) : undefined)));
+        // 监听器返回面 unknown（通知型契约）——收口侧由调用方以 R 断言（并发计算型的
+        // 类型对齐是调用方契约，存储侧无从静态验证）
+        return results;
+    }
+    /**
+     * 排队串行：逐监听器顺序执行（后段等前段完成）；不短路——异常隔离上报后
+     * 继续下一段（与 waterfall 的区别 = 无委托链、异常不停段）。
+     * 同词多次派发按到达序排队（per-name 链式 promise）。
+     */
+    serial(name, data) {
+        this.assertRegistered(name);
+        const legs = (this.listeners.get(name) ?? []).map((entry) => entry.notify);
+        const tail = this.serialQueues.get(name) ?? Promise.resolve();
+        const run = tail.then(async () => {
+            for (const listener of legs) {
+                try {
+                    await listener?.(data);
+                }
+                catch (err) {
+                    this.onListenerError(name, err);
+                }
+            }
+        });
+        // 队尾吞异常（隔离语义：一次派发的失败不堵后续派发的排队）
+        this.serialQueues.set(name, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    /** 未注册词执法（emit/on/waterfall/parallel/serial 共用） */
+    assertRegistered(name) {
+        if (!this.registered.has(name)) {
+            throw new BaseError('EVENT_NOT_REGISTERED', `事件词 ${name} 未注册——fail-loud（词汇注册表单源，先 registerEventNames）`);
+        }
+    }
+}

package/dist/context/index.js

@@ -0,0 +1,13 @@
+/**
+ * context 模块公开面（L1 运行时基座——02 §2.2；一切件在其上）。
+ *
+ * 本批落码：作用域（effect LIFO 回卷/fork 级联/stale 护栏）+ 事件分派四模式
+ * + provide/get 服务注册表 + 自写 logger + canonical 工作区根。
+ * jiti 加载原语与目录信任判定随 host 装载批定形（消费面 = 插件装载器——
+ * 契约先于实现的纵切序），02 §2.2 职责清单不变。
+ */
+import './codes.js';
+export { Scope, SCOPE_EFFECT_CAPACITY } from './scope.js';
+export { EventDispatch } from './events.js';
+export { LogLevelState, createLogger, childLogger } from './logger.js';
+export { canonicalWorkspaceRoot, clearWorkspaceRootCache } from './workspace.js';

package/dist/context/logger.js

@@ -0,0 +1,136 @@
+/**
+ * 自写轻量 logger（07 §6 日志级别策略——约百行，不引入日志库）。
+ *
+ * 细则逐条：
+ *  - 级别四档 error/warn/info/debug + silent 全静默；缺省 info（发布物即生产）；
+ *  - 结构化 JSON 行（time/level/module/msg + 上下文字段）写 stderr；
+ *  - 模块前缀分级：BERRY_AGENT_LOG_LEVEL 逗号分隔 per-module 条目
+ *    （`info,session:debug`）；条目按 lastIndexOf(':') 切分（模块名含冒号可表达
+ *    ——`core:memory` 里的冒号不是分隔符）；前缀匹配（`session` 命中 `session`
+ *    与 `session:*` 全体）；
+ *  - 共享阈值盒：同盒树的 logger 持同一盒引用，setLevel 改盒值全树即时生效；
+ *    child logger 不入登记表（防慢性泄漏）；
+ *  - 无效条目 stderr 警告后跳过（视同未设——静默失效比无反馈更糟）；
+ *  - 纪律红线（消费方义务）：只在 debug 出现的分支，其行为必须同时是 durable
+ *    事件或运行时断言——进程日志职责收窄为「启动/崩溃/守门/恢复」诊断。
+ */
+/** 级别权重（数值越大越啰嗦——debug 3 最详；silent 独立档不入权重表） */
+const LEVEL_WEIGHTS = { error: 0, warn: 1, info: 2, debug: 3 };
+/**
+ * 阈值盒（共享状态）：全局级 + per-module 前缀覆盖表。
+ * createLogger 树全体持同一盒引用——setGlobalLevel/setModuleLevel 改盒即全树
+ * 即时生效；盒本身即解析态，logger 对象不入任何登记表。
+ */
+export class LogLevelState {
+    /** 全局阈值（缺省 info——发布物即生产） */
+    global = 'info';
+    /** per-module 前缀覆盖（前缀 → 级别；匹配取最长前缀） */
+    modules = new Map();
+    /** 从 env 串建盒（无效条目 stderr 警告后跳过——视同未设） */
+    static fromEnv(env, warn = defaultEnvWarn) {
+        const state = new LogLevelState();
+        if (!env)
+            return state;
+        for (const rawEntry of env.split(',')) {
+            const entry = rawEntry.trim();
+            if (!entry)
+                continue;
+            // lastIndexOf(':') 切分：模块名含冒号（core:memory）可表达——
+            // 最右一个冒号才是「模块:级别」分隔符
+            const sep = entry.lastIndexOf(':');
+            const levelText = sep >= 0 ? entry.slice(sep + 1) : entry;
+            const moduleText = sep >= 0 ? entry.slice(0, sep) : '';
+            const level = parseLevel(levelText);
+            if (!level) {
+                warn(`BERRY_AGENT_LOG_LEVEL 无效条目 "${entry}"（级别 "${levelText}" 不在闭集 error|warn|info|debug|silent）——已跳过`);
+                continue;
+            }
+            if (sep >= 0 && moduleText)
+                state.modules.set(moduleText, level);
+            else
+                state.setGlobalLevel(level);
+        }
+        return state;
+    }
+    /** 改全局阈值（全树即时生效——运行期提降级面） */
+    setGlobalLevel(level) {
+        this.global = level;
+    }
+    /** 设/覆盖某模块前缀阈值（前缀匹配：`session` 命中 `session` 与 `session:*` 全体） */
+    setModuleLevel(prefix, level) {
+        this.modules.set(prefix, level);
+    }
+    /** 解析模块生效级：最长匹配前缀条目 ?? 全局（silent 压倒一切——显式全静默） */
+    resolve(module) {
+        if (this.global === 'silent')
+            return 'silent';
+        let best;
+        for (const [prefix, level] of this.modules) {
+            // 前缀匹配：模块名等于前缀、或以前缀+':' 开头（域分段符）
+            const matches = module === prefix || module.startsWith(`${prefix}:`);
+            if (!matches)
+                continue;
+            if (!best || prefix.length > best.prefix.length)
+                best = { prefix, level };
+        }
+        const resolved = best?.level ?? this.global;
+        return resolved === 'silent' ? 'silent' : resolved;
+    }
+}
+/** 单条级别字面量解析（大小写不敏感；无效返回 null） */
+function parseLevel(text) {
+    const lower = text.toLowerCase();
+    if (lower === 'silent')
+        return 'silent';
+    if (lower in LEVEL_WEIGHTS)
+        return lower;
+    return null;
+}
+/** env 无效值警告的缺省面（bootstrapping 阶段 stderr 一行） */
+function defaultEnvWarn(msg) {
+    process.stderr.write(`[logger] ${msg}\n`);
+}
+/**
+ * logger → 内部三件（盒/sink/clock）弱关联：childLogger 派生的唯一缝。
+ * WeakMap 不阻回收（logger 亡即条目亡——「不入登记表防慢性泄漏」的兑现形态：
+ * 强引用登记表不存在，弱关联只为派生期取参）。
+ */
+const loggerInternals = new WeakMap();
+/**
+ * 建模块 logger（child 面共享 state 盒——树内全树同盒即时生效）。
+ * @param module 模块名（域分段用 ':'——如 `session`、`core:memory`）
+ * @param state 共享阈值盒（缺省独立盒 info——测试/独立小面用；ctx 装配时传同一盒）
+ * @param sink 输出面（缺省 process.stderr；测试注入内存）
+ * @param clock 时间源（缺省 Date.now——测试可注入定值）
+ */
+export function createLogger(module, state = new LogLevelState(), sink = (line) => process.stderr.write(`${line}\n`), clock = Date.now) {
+    const write = (level, msg, fields) => {
+        const resolved = state.resolve(module);
+        if (resolved === 'silent')
+            return;
+        if (LEVEL_WEIGHTS[level] > LEVEL_WEIGHTS[resolved])
+            return;
+        // 结构化 JSON 行：time/level/module/msg + 上下文字段平铺
+        sink(JSON.stringify({ time: clock(), level, module, msg, ...fields }));
+    };
+    const logger = {
+        module,
+        debug: (msg, fields) => write('debug', msg, fields),
+        info: (msg, fields) => write('info', msg, fields),
+        warn: (msg, fields) => write('warn', msg, fields),
+        error: (msg, fields) => write('error', msg, fields),
+    };
+    loggerInternals.set(logger, { state, sink, clock });
+    return logger;
+}
+/**
+ * 派生 child logger（`session` → `session:sqlite` 式域细分）：同盒同 sink 同
+ * clock——setLevel 改盒全树（含 child）即时生效。仅接受 createLogger 产物。
+ */
+export function childLogger(parent, subModule) {
+    const internals = loggerInternals.get(parent);
+    if (!internals) {
+        throw new Error('childLogger 仅接受 createLogger 产物（缺内部面——勿手工构造 Logger 对象）');
+    }
+    return createLogger(`${parent.module}:${subModule}`, internals.state, internals.sink, internals.clock);
+}

package/dist/context/scope.js

@@ -0,0 +1,182 @@
+/**
+ * 作用域与服务注册表（04 §6「作用域与事件四模式」前半）。
+ *
+ * 三机制：
+ *  - **effect LIFO 回卷**：ctx.effect(() => disposer) 登记可逆副作用，作用域
+ *    teardown 按登记逆序回卷全部 disposer——装载了什么就必然能卸干净（痕迹
+ *    可清算）。生命周期绑位（进程根/会话/run 三级）由使用方创建，本模块只提供机制。
+ *  - **fork 级联**：scope.fork() 派生子作用域——子先于父回卷、父回卷级联全部
+ *    未卷子。fork 不是拷贝：provide 面继承（子见父服务）、effect 面独立。
+ *  - **stale 护栏**：作用域已回卷后完成的异步腿经 stale 判定收口——迟到的
+ *    disposer 不再执行（回卷已过）、迟到的服务注册拒绝（SCOPE_STALE）。
+ *  - **总注册帽**：effect 自有登记达 10^4 拒新登记（SCOPE_EFFECT_CAPACITY——
+ *    03 §3.4 可用性防线，真源即执法位点）。
+ */
+import { BaseError } from '../contracts/index.js';
+/**
+ * effect 总注册帽（03 §3.4：10^4——可用性防线，失控登记不拖垮回卷序）。
+ * 真源即执法位点：自有 disposers 长度即计数，无第二计数位（包装层形否决——
+ * 帽下帽双重记账〔03 §3.4 遗漏审计批钉位〕）；fork 面独立同律（子作用域
+ * 各有自有帽，级联回卷总量不受限）。导出供测试与文档引用。
+ */
+export const SCOPE_EFFECT_CAPACITY = 10_000;
+/**
+ * 作用域：服务注册面（provide/get）+ 可逆注册面（effect）+ fork 树。
+ * 生命周期三级（进程根/会话/run）= 三次 createScope/fork 的使用形态。
+ */
+export class Scope {
+    /** 父作用域（fork 派生关系；根作用域为 undefined） */
+    parent;
+    /** 自有服务注册（fork 面继承 = get 沿父链上溯；子重提供同名 = 遮蔽合法） */
+    services = new Map();
+    /**
+     * 服务主位账（同主刷新律——04 §6 定形注：/reload 撬名修复批）。键值与
+     * services 同集（每次成功 provide 同步落位；匿名提供 = undefined 位）。
+     * 刷新判据专用，不另设公共读面。
+     */
+    owners = new Map();
+    /** 已登记 disposer（登记序）——回卷按逆序 LIFO */
+    disposers = [];
+    /** 未回卷的子作用域（父回卷时级联先卷） */
+    children = new Set();
+    /** 回卷旗标（stale 护栏判据；回卷后一切迟到登记拒） */
+    disposed = false;
+    /** @param parent 父作用域（缺省 = 根作用域）；派生走 fork() 不直调本构造器 */
+    constructor(parent) {
+        this.parent = parent;
+    }
+    /** 创建根作用域（进程根/会话/run 三级的使用入口之一） */
+    static createRoot() {
+        return new Scope(undefined);
+    }
+    /**
+     * 派生子作用域：子先于父回卷（逆序天然）、父回卷级联全部未卷子；
+     * provide 面继承（get 上溯）、effect 面独立（子的副作用不污染父的回卷序）。
+     */
+    fork() {
+        if (this.disposed)
+            throw new BaseError('SCOPE_STALE', '父作用域已回卷——不能再派生子作用域');
+        const child = new Scope(this);
+        this.children.add(child);
+        return child;
+    }
+    /** 作用域是否已回卷（异步腿竞速收口的 stale 判据） */
+    get isDisposed() {
+        return this.disposed;
+    }
+    /**
+     * 登记服务（装载期接线、运行期取用）。
+     * 撞名分档（同主刷新律——04 §6 定形注）：同 owner 重供 = 原位刷新
+     * （upsert——依赖方下次取用即见新值；`/reload` 换代重跑同装配位的结构性
+     * 支撑）；跨主撞名与匿名重供（任一方匿名即不可证明同主）照旧拒
+     * CONTEXT_SERVICE_DUPLICATE（两方抢一名仍是装配 bug）。
+     * owner 真源 = 装载器注入非自报（ctx.provide 恒 = 本插件 id——包装层注入；
+     * 宿主装配位 = 装配位标识）。迟到注册（已回卷）拒 SCOPE_STALE。
+     */
+    provide(name, service, owner) {
+        if (this.disposed)
+            throw new BaseError('SCOPE_STALE', `迟到注册拒：作用域已回卷（${name}）`);
+        if (this.services.has(name)) {
+            const prevOwner = this.owners.get(name);
+            // 匿名任一方即拒：undefined 位不可被刷新（无法证明同主），带主重供匿名
+            // 位同理——防匿名注册经刷新律洗白为带主位
+            if (owner === undefined || prevOwner === undefined || owner !== prevOwner) {
+                throw new BaseError('CONTEXT_SERVICE_DUPLICATE', `服务名 ${name} 在本作用域已被提供（fork 子作用域重提供 = 遮蔽合法，同层撞名 = 装配 bug；同主重供 = 原位刷新）`);
+            }
+            // 同主原位刷新——非新增（serviceNames 名册零重复）
+            this.services.set(name, service);
+            return;
+        }
+        this.services.set(name, service);
+        this.owners.set(name, owner);
+    }
+    /**
+     * 取服务（沿 fork 链上溯——provide 面继承）。
+     * 缺席 fail-loud（CONTEXT_SERVICE_MISSING，拼错名立即炸）。
+     * 判缺席用沿链 has 而非值判 undefined——已注册的 undefined 值服务不算缺席。
+     */
+    get(name) {
+        let scope = this;
+        while (scope) {
+            if (scope.services.has(name))
+                return scope.services.get(name);
+            scope = scope.parent;
+        }
+        throw new BaseError('CONTEXT_SERVICE_MISSING', `服务 ${name} 缺席（拼错名/装载序缺口——可选消费用 tryGet）`);
+    }
+    /** 可选消费（「诚实缺席不 fail-loud」的唯一档——如浏览器引擎缺席） */
+    tryGet(name) {
+        // 沿父链上溯：自有无则问父——fork 继承语义
+        let scope = this;
+        while (scope) {
+            if (scope.services.has(name))
+                return scope.services.get(name);
+            scope = scope.parent;
+        }
+        return undefined;
+    }
+    /**
+     * 沿 fork 链枚举可见服务名（自身 + 全部祖先，就近在前）。
+     * 03 §3.1「服务目录运行时可枚举」的机制腿——ctx.get 缺席报错附现行名单，
+     * 点名错误当场响亮可诊。子遮蔽父同名时两现（就近位次即遮蔽序——诚实枚举）。
+     */
+    serviceNames() {
+        const names = [];
+        let scope = this;
+        while (scope) {
+            names.push(...scope.services.keys());
+            scope = scope.parent;
+        }
+        return names;
+    }
+    /**
+     * 登记可逆副作用：register 立即执行、其返回的 disposer 进 LIFO 回卷序。
+     * 迟到登记（已回卷）拒 SCOPE_STALE——迟到的 disposer 不再执行（回卷已过，
+     * 补跑只会撕裂状态）。
+     */
+    effect(register) {
+        if (this.disposed)
+            throw new BaseError('SCOPE_STALE', '迟到登记拒：作用域已回卷（disposer 补跑只会撕裂状态）');
+        // 总注册帽（03 §3.4 钉 10^4）：拒在 register 回调执行前——超帽受理连副作用都不发生
+        if (this.disposers.length >= SCOPE_EFFECT_CAPACITY) {
+            throw new BaseError('SCOPE_EFFECT_CAPACITY', `effect 总注册帽（${SCOPE_EFFECT_CAPACITY}）已满——本作用域登记数已达上限（失控登记防线，宿主/插件同帽一视）`);
+        }
+        const disposer = register();
+        // register 返回后仍可能已并发回卷——回卷序已定格的 disposer 直接执行收口，
+        // 不入序（防撕裂：单独跑一次再丢弃，副作用「必然被清算」承诺保持）
+        if (this.disposed) {
+            void Promise.resolve(disposer()).catch(() => {
+                // 迟到腿的清理失败静默（作用域已亡，无回收面——吞并是唯一不撕裂选择）
+            });
+            return;
+        }
+        this.disposers.push(disposer);
+    }
+    /**
+     * 回卷作用域：子先级联回卷 → 自有 disposer 按 LIFO 逆序回卷 → 标记 disposed。
+     * 幂等（二次调用直接返回）；disposer 异常不中断回卷（清算是尽力序——
+     * 单腿炸不掩护其余腿的清算义务）。
+     */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // 级联：子先于父回卷（父回卷时把未卷的子全卷）
+        for (const child of [...this.children]) {
+            await child.dispose();
+        }
+        this.children.clear();
+        if (this.parent)
+            this.parent.children.delete(this);
+        // LIFO：后登记的先回卷（登记逆序）
+        for (const disposer of this.disposers.reverse()) {
+            try {
+                await disposer();
+            }
+            catch {
+                // 单腿回卷失败不中断其余腿清算（尽力序；失败腿无二次重试面）
+            }
+        }
+        this.disposers.length = 0;
+    }
+}

package/dist/context/workspace.js

@@ -0,0 +1,104 @@
+/**
+ * canonical 工作区根原语（06 §「owner_key 与 canonical 工作区根」；02 §2.2
+ * context 职责——共享原语宿主收编：memory owner_key / 技能信任判定 / 未来
+ * project 域键三处同源，一处实现三处消费）。
+ *
+ * 解析律（06 §74 逐条）：
+ *  - 从 cwd 向上找最近 `.git`；
+ *  - worktree / submodule（`.git` 为文件）解析 `gitdir → commondir` 归并到
+ *    主仓库根——同一仓库的主目录、worktree、任意子目录产生同一 project 键；
+ *  - 非 git 目录回退字面 cwd；
+ *  - submodule 的 modules gitdir 无 commondir，独立成域（submodule 本就是
+ *    独立仓库）——canonical 根取 gitdir 实身；
+ *  - 探测结果按 cwd 进程内缓存（同路径不重复打 fs；仓库移动属极端场景，
+ *    重启自愈）；
+ *  - 不读 GIT_* 宿主环境变量（03 篇配置总线禁令同向）。
+ */
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+/** 探测缓存（cwd → canonical 根；进程内单例——同路径不重复打 fs） */
+const cache = new Map();
+/**
+ * 解析 canonical 工作区根。
+ * @param cwd 起点目录（缺省 process.cwd）；结果按 cwd 缓存
+ * @returns canonical 根绝对路径（realpath 后的主仓库根 / gitdir 实身 / 字面 cwd 回退）
+ */
+export function canonicalWorkspaceRoot(cwd = process.cwd()) {
+    const cached = cache.get(cwd);
+    if (cached !== undefined)
+        return cached;
+    const root = detect(cwd);
+    cache.set(cwd, root);
+    return root;
+}
+/** 清空探测缓存（测试用——生产面无清空路径） */
+export function clearWorkspaceRootCache() {
+    cache.clear();
+}
+/** 实际探测（无缓存路径） */
+function detect(cwd) {
+    // 逐级上溯找最近 .git（含 cwd 自身；existsSync 对断链符号链返回 false——
+    // statSync lstat 语义此处不需要，直接 existsSync 探测文件/目录均可）
+    let dir = resolve(cwd);
+    let gitPath;
+    for (;;) {
+        const candidate = join(dir, '.git');
+        if (pathExists(candidate)) {
+            gitPath = candidate;
+            break;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // 到文件系统根仍未命中
+        dir = parent;
+    }
+    if (!gitPath) {
+        // 非 git 目录：回退字面 cwd（resolve 归一，不做 realpath——字面语义）
+        return resolve(cwd);
+    }
+    const st = statSync(gitPath);
+    if (st.isDirectory()) {
+        // 普通仓库：.git 目录的父级即仓库根（realpath 消符号链）
+        return realpathSync(dirname(gitPath));
+    }
+    // .git 是文件：worktree / submodule——解析 gitdir: 行
+    const gitdir = parseGitdir(gitPath);
+    if (!gitdir) {
+        // 无法解析的 .git 文件（畸形）：退字面 cwd（宁可退也不炸探测）
+        return resolve(cwd);
+    }
+    const commondirPath = join(gitdir, 'commondir');
+    if (pathExists(commondirPath)) {
+        // worktree：commondir 内容指向主 .git 目录（相对 commondirPath 所在目录或
+        // 绝对路径）——归并到主仓库根（主目录/worktree/子目录同一键的兑现点）
+        const content = readFileSync(commondirPath, 'utf8').trim();
+        const mainGitDir = isAbsolute(content) ? content : resolve(dirname(commondirPath), content);
+        return realpathSync(dirname(mainGitDir));
+    }
+    // submodule：modules gitdir 无 commondir——独立成域，gitdir 实身即根
+    return realpathSync(gitdir);
+}
+/** .git 文件解析 gitdir: 行（无该行/读失败返回 undefined） */
+function parseGitdir(gitFile) {
+    try {
+        const content = readFileSync(gitFile, 'utf8');
+        for (const line of content.split('\n')) {
+            if (line.startsWith('gitdir:'))
+                return line.slice('gitdir:'.length).trim();
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 存在性探测（文件或目录均可；异常视同不存在——探测不炸） */
+function pathExists(p) {
+    try {
+        statSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/contracts/agent-events.d.ts

@@ -0,0 +1,73 @@
+/**
+ * AgentEvent 活体事件族契约（04 篇 §2 机制真源——10 型，内存直推、不落日志）。
+ *
+ * 归位注记（2026-09-08 U3 落码批）：本族类型原住 agent 件（src/agent/events.ts），
+ * 为插件侧 UI 后端类型可达（03 §2.2 registerUiBackend 定形注记——虚拟主键
+ * `berry-agent` 面只达 contracts）随 U3-1 归位本件；类型闭包全 contracts 侧
+ * （AgentMessage/StopReason/AgentToolResult 既在本域），机制真源仍 04 §2、
+ * agent 件经 re-export 维持公开面与件内消费路径不变（批 11b ApprovalAsk
+ * 归位同款先例）。
+ *
+ * 顺序铁律：每族严格 `start → update* → end`；流式 delta 与工具进度经 update
+ * 携带。活体流单向消费、不可逆写 durable（05 篇 §7 分层不变式）——「活体呈现」
+ * 与「durable 真相」两条线永不合流。重试续入零新事件型：续入即新
+ * agent_start/message 流，用户看到重跑。
+ */
+import type { StopReason } from './llm.js';
+import type { AgentMessage } from './messages.js';
+import type { AgentToolResult } from './tools.js';
+/** run 终态恰三值（04 篇 §2：终态是结算边界——Job 结算、审批对收口、预算记账截断都以它为锚） */
+export type RunStatus = 'completed' | 'aborted' | 'failed';
+/**
+ * 三通道词表（04 篇 §4）：steer = busy 注入合批 / followUp = idle 起跑 /
+ * inject = dismantled 停摆后注入。发送方只声明 backgroundWake、三通道判定是
+ * 驱动侧单源（conversation）——本词表只承载判定结果（活体事件字段，用户能
+ * 看到消息进了哪条道）。
+ */
+export type DeliverChannel = 'steer' | 'followUp' | 'inject';
+/**
+ * AgentEvent 10 型联合。message_start/message_end 携带 channel（可观测性：
+ * 消息经哪条通道入列——04 §4；channel 缺省 = 用户直发种子消息）。
+ */
+export type AgentEvent = {
+    type: 'agent_start';
+} | {
+    type: 'agent_end';
+    status: RunStatus;
+    stopReason?: StopReason;
+    errorMessage?: string;
+} | {
+    type: 'turn_start';
+    turn: number;
+} | {
+    type: 'turn_end';
+    turn: number;
+    stopReason: StopReason;
+} | {
+    type: 'message_start';
+    role: string;
+    channel?: DeliverChannel;
+} | {
+    type: 'message_update';
+    role: string;
+    partial: AgentMessage;
+} | {
+    type: 'message_end';
+    message: AgentMessage;
+    channel?: DeliverChannel;
+} | {
+    type: 'tool_execution_start';
+    toolCallId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'tool_execution_update';
+    toolCallId: string;
+    update: unknown;
+} | {
+    type: 'tool_execution_end';
+    toolCallId: string;
+    result: AgentToolResult;
+};
+/** 事件汇（消费面：TUI/SPA 活体呈现、金样录制器等；void/Promise 双形兼容） */
+export type AgentEventSink = (event: AgentEvent) => void | Promise<void>;