berry-agent 0.1.0-alpha.1

package/dist/host/cli.js

@@ -0,0 +1,544 @@
+/**
+ * 扫描一段 argv：旗标消费 + 裸 `--` 终结符 + 位置参数收集 + help/version 越位记录。
+ *
+ * - 未识别 `--` 词 → error（执法①）；
+ * - 取值旗标值缺席 / 空串 / 以 `--` 起头（占位缺失裁量）/ 值域外 / 非正整数 → error（执法③）；
+ * - optional-value 仅当下一词存在且不以 `--` 起头时消费（--fork 形专用）。
+ */
+function scanFlags(argv, schemas) {
+    const booleans = new Set();
+    const values = new Map();
+    const literals = [];
+    let overreach;
+    const byName = new Map(schemas.map((s) => [s.name, s]));
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === '--') {
+            // 裸终结符：余下全字面（执法②——正当以 -- 起头的消息内容保真送达）
+            literals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (tok.startsWith('--')) {
+            const name = tok.slice(2);
+            if (name === 'help' || name === 'version') {
+                overreach ??= tok; // 记录首个越位词（执法④）
+                continue;
+            }
+            const schema = byName.get(name);
+            if (!schema) {
+                return { booleans, values, literals, overreach, error: `未识别旗标 --${name}（全部旗标见 --help）` };
+            }
+            if (schema.kind === 'boolean') {
+                booleans.add(name);
+                continue;
+            }
+            if (schema.kind === 'optional-value') {
+                // 可选值形（--fork 专用）：下一词存在且不以 `--` 起头才消费为值；否则记空串哨兵 = 在场无值
+                const next = argv[i + 1];
+                if (next !== undefined && next !== '' && !next.startsWith('--')) {
+                    values.set(name, next);
+                    i++;
+                }
+                else {
+                    values.set(name, '');
+                }
+                continue;
+            }
+            const next = argv[i + 1];
+            if (next === undefined || next === '' || next.startsWith('--')) {
+                return { booleans, values, literals, overreach, error: `--${name} 须带值（空串占位或缺失即用法错）` };
+            }
+            if (schema.values && !schema.values.includes(next)) {
+                return {
+                    booleans,
+                    values,
+                    literals,
+                    overreach,
+                    error: `--${name} 值域外：${next}（合法值：${schema.values.join('|')}）`,
+                };
+            }
+            if (schema.positiveInt) {
+                const n = Number(next);
+                if (!Number.isInteger(n) || n < 1 || n > schema.positiveInt.upTo) {
+                    return {
+                        booleans,
+                        values,
+                        literals,
+                        overreach,
+                        error: `--${name} 须为 1–${schema.positiveInt.upTo} 的整数（收到：${next}）`,
+                    };
+                }
+            }
+            if (schema.nonNegativeInt) {
+                const n = Number(next);
+                if (!Number.isInteger(n) || n < 0 || n > schema.nonNegativeInt.upTo) {
+                    return {
+                        booleans,
+                        values,
+                        literals,
+                        overreach,
+                        error: `--${name} 须为 0–${schema.nonNegativeInt.upTo} 的整数（收到：${next}）`,
+                    };
+                }
+            }
+            values.set(name, next);
+            i++;
+            continue;
+        }
+        literals.push(tok);
+    }
+    return { booleans, values, literals, overreach };
+}
+function usageFail(message) {
+    return { ok: false, exitCode: 2, message };
+}
+/** 位置参数计数执法（不足/超出即退 2——usage 形描述期望） */
+function expectArity(literals, min, max, usage) {
+    if (literals.length < min || literals.length > max) {
+        return usageFail(`位置参数数目不符（期望 ${min === max ? `恰 ${min}` : `${min}–${max}`}，收到 ${literals.length}）——用法：${usage}`);
+    }
+    return literals;
+}
+/* ---------------- 各入口旗标表（07 §5 旗标块收面逐条钉位） ---------------- */
+/** 通用三旗标（--port/--no-plugins/--debug）——按入口拼装（自动化入口不透传 --no-plugins） */
+const PORT_FLAG = { name: 'port', kind: 'value', positiveInt: { upTo: 65535 } };
+const NO_PLUGINS_FLAG = { name: 'no-plugins', kind: 'boolean' };
+const DEBUG_FLAG = { name: 'debug', kind: 'boolean' };
+/** 快速试件旗标（--plugin-file <path>——TUI/run 两入口收；dump-config 收而互斥拒） */
+const PLUGIN_FILE_FLAG = { name: 'plugin-file', kind: 'value' };
+const TUI_SCHEMAS = [PORT_FLAG, NO_PLUGINS_FLAG, DEBUG_FLAG, PLUGIN_FILE_FLAG];
+const RUN_SCHEMAS = [
+    PORT_FLAG,
+    NO_PLUGINS_FLAG,
+    DEBUG_FLAG,
+    { name: 'read-only', kind: 'boolean' },
+    // --tick <名>：取值形（批 20a——15a runner argv 先行定形 cli 侧跟齐；07 §5 同笔定名）
+    { name: 'tick', kind: 'value' },
+    { name: 'background', kind: 'boolean' },
+    { name: 'output-format', kind: 'value', values: ['text', 'json', 'stream'] },
+    { name: 'no-delta', kind: 'boolean' },
+    { name: 'output-last-message', kind: 'value' },
+    { name: 'ephemeral', kind: 'boolean' },
+    { name: 'max-turns', kind: 'value', positiveInt: { upTo: 1000 } },
+    { name: 'session', kind: 'value' },
+    { name: 'continue', kind: 'boolean' },
+    { name: 'fork', kind: 'optional-value' },
+    // --output-schema 未实现：显式传入即用法错退 2 不静默忽略（07 §5——实现随批 13 落地翻转）
+    { name: 'output-schema', kind: 'boolean' },
+    // --preset <名>：权限预设逐次形（04 §9 ⑥ ap-3——值域三档单源 safety/presets；
+    // 与 --read-only 互斥在 parseRun 执法——同层 mode 冲突）
+    { name: 'preset', kind: 'value', values: ['conservative', 'balanced', 'open'] },
+    // --plugin-file <path>：快速试件（03 §7 生态启动批 eco-3a——TUI 同位同语义）
+    PLUGIN_FILE_FLAG,
+];
+const SERVE_SCHEMAS = [
+    PORT_FLAG,
+    DEBUG_FLAG,
+    { name: 'daemon', kind: 'boolean' },
+    { name: 'no-delta', kind: 'boolean' },
+    // daemon 形专属（07 §5 落码定名批）：TCP 侧可选两旗标——前台 stdio 形无
+    // HTTP 面，传入即用法错（parseServe 互斥执法——防「收下不起」静默吞）
+    { name: 'sdk-port', kind: 'value', positiveInt: { upTo: 65535 } },
+    { name: 'sdk-host', kind: 'value' },
+];
+const DUMP_SCHEMAS = [PORT_FLAG, NO_PLUGINS_FLAG, DEBUG_FLAG, PLUGIN_FILE_FLAG];
+const UNINSTALL_SCHEMAS = [
+    { name: 'confirm', kind: 'boolean' },
+    { name: 'data', kind: 'value', values: ['keep', 'purge'] },
+];
+/** install 旗标族（07 §5——--min-release-age 逐次覆盖 env 静置窗；0 = 显式关窗故走非负整数域） */
+const INSTALL_SCHEMAS = [
+    { name: 'min-release-age', kind: 'value', nonNegativeInt: { upTo: 10_000_000 } },
+];
+/* ---------------- 命令解析器 ---------------- */
+/** 解析 run 命令段（子命令位已消费） */
+function parseRun(rest) {
+    const scan = scanFlags(rest, RUN_SCHEMAS);
+    if (scan.error)
+        return usageFail(scan.error);
+    // --output-schema 显式传入即退 2（未实现——不静默忽略）
+    if (scan.booleans.has('output-schema')) {
+        return usageFail('--output-schema 尚未实现——显式传入即用法错（不静默忽略；实现随 SDK 通道批落地后翻转本闸）');
+    }
+    // --tick <名> 取值形（批 20a）：与 message 位置参数互斥——到点形态提示词在行内不在
+    // argv（07 §5 定名）；arity 随形态分档（--tick 在场零位置参数、缺席恰一）
+    const tickName = scan.values.get('tick');
+    if (tickName !== undefined && scan.literals.length > 0) {
+        return usageFail('--tick 与 message 位置参数互斥（到点形态提示词在 jobs 行内不在 argv）');
+    }
+    const msg = tickName !== undefined ? [] : expectArity(scan.literals, 1, 1, 'berry-agent run "<message>"');
+    if ('exitCode' in msg)
+        return msg;
+    const has = (b) => scan.booleans.has(b);
+    // 互斥组执法（执法⑤）：--ephemeral × 续接族 + --tick/--background（续接族里 --session/--fork 是取值旗标——判在场看 values）
+    if (has('ephemeral')) {
+        const clash = scan.values.has('session') ||
+            has('continue') ||
+            scan.values.has('fork') ||
+            tickName !== undefined ||
+            has('background');
+        if (clash) {
+            return usageFail('--ephemeral 与 --session/--continue/--fork/--tick/--background 互斥（零落盘会话不进续接/定时/后台复用）');
+        }
+    }
+    // 续接族三者互斥
+    const resumePicks = (scan.values.has('session') ? 1 : 0) + (has('continue') ? 1 : 0) + (scan.values.has('fork') ? 1 : 0);
+    if (resumePicks > 1) {
+        return usageFail('--session / --continue / --fork 三者互斥（续接显式 opt-in 单选）');
+    }
+    // --read-only × --preset 互斥（ap-3）：同为 CLI 层 sandbox 档定值位——预设
+    // 档已含沙箱档位（conservative=read-only/balanced|open=workspace-write），
+    // 同层冲突单选免层内优先级暗规则（04 §9 ⑥ ap-3 定形补充）
+    const preset = scan.values.get('preset');
+    if (preset !== undefined && has('read-only')) {
+        return usageFail('--read-only 与 --preset 互斥（预设档已含沙箱档位——单选：conservative=read-only / balanced|open=workspace-write）');
+    }
+    const port = scan.values.get('port');
+    const maxTurns = scan.values.get('max-turns');
+    const flags = {
+        port: port === undefined ? undefined : Number(port),
+        noPlugins: has('no-plugins'),
+        debug: has('debug'),
+        readOnly: has('read-only'),
+        tick: tickName,
+        background: has('background'),
+        outputFormat: scan.values.get('output-format'),
+        noDelta: has('no-delta'),
+        outputLastMessage: scan.values.get('output-last-message'),
+        ephemeral: has('ephemeral'),
+        maxTurns: maxTurns === undefined ? undefined : Number(maxTurns),
+        session: scan.values.get('session'),
+        continueLatest: has('continue'),
+        fork: scan.values.has('fork') ? { id: scan.values.get('fork') || undefined } : undefined,
+        preset,
+        pluginFile: scan.values.get('plugin-file'),
+    };
+    // tick 形 message 置空串（CliCommand 契约 string 必填保持——run-entry 按
+    // flags.tick 判到点形态，不消费 message 位；非 tick 形 arity 已保恰一非空）
+    const command = { kind: 'run', message: msg[0] ?? '', flags };
+    return finish(scan, command);
+}
+/** 解析 serve 命令段（serve status/serve stop 已在首层分派——此处仅 serve 本体） */
+function parseServe(rest) {
+    const scan = scanFlags(rest, SERVE_SCHEMAS);
+    if (scan.error)
+        return usageFail(scan.error);
+    const arity = expectArity(scan.literals, 0, 0, 'berry-agent serve [--daemon] [--port <n>] [--sdk-port <n>] [--sdk-host <host>]');
+    if ('exitCode' in arity)
+        return arity;
+    // daemon 形专属旗标互斥执法（执法⑤同族）：--sdk-port/--sdk-host 是 daemon 形
+    // sdk HTTP 面 TCP 侧可选（07 §5 落码定名批）——前台 stdio 形传入即用法错
+    if (!scan.booleans.has('daemon') && (scan.values.has('sdk-port') || scan.values.has('sdk-host'))) {
+        return usageFail('--sdk-port/--sdk-host 为 --daemon 形态专属（前台 stdio 形无 HTTP 面）');
+    }
+    const port = scan.values.get('port');
+    const sdkPort = scan.values.get('sdk-port');
+    const command = {
+        kind: 'serve',
+        flags: {
+            port: port === undefined ? undefined : Number(port),
+            debug: scan.booleans.has('debug'),
+            daemon: scan.booleans.has('daemon'),
+            noDelta: scan.booleans.has('no-delta'),
+            sdkPort: sdkPort === undefined ? undefined : Number(sdkPort),
+            sdkHost: scan.values.get('sdk-host'),
+        },
+    };
+    return finish(scan, command);
+}
+/** 解析 plugins 子命令段 */
+function parsePlugins(rest) {
+    const [head, ...tail] = rest;
+    if (head === undefined || head.startsWith('--')) {
+        return usageFail('plugins 须带子命令（list/install/uninstall/mount/unmount/toggle/update/check）');
+    }
+    switch (head) {
+        case 'list':
+        case 'check': {
+            const scan = scanFlags(tail, []);
+            if (scan.error)
+                return usageFail(scan.error);
+            const arity = expectArity(scan.literals, 0, 0, `berry-agent plugins ${head}`);
+            if ('exitCode' in arity)
+                return arity;
+            return finish(scan, { kind: 'plugins', sub: { sub: head } });
+        }
+        case 'install': {
+            const scan = scanFlags(tail, INSTALL_SCHEMAS);
+            if (scan.error)
+                return usageFail(scan.error);
+            const args = expectArity(scan.literals, 1, 1, 'berry-agent plugins install <ref> [--min-release-age <分钟>]');
+            if ('exitCode' in args)
+                return args;
+            const ageRaw = scan.values.get('min-release-age');
+            // 非负整数域已由 scanFlags 执法——此处仅 Number 化（CLI > env > 缺省三级缺一）
+            const minReleaseAge = ageRaw === undefined ? undefined : Number(ageRaw);
+            return finish(scan, {
+                kind: 'plugins',
+                sub: {
+                    sub: 'install',
+                    ref: args[0],
+                    ...(minReleaseAge !== undefined ? { minReleaseAge } : {}),
+                },
+            });
+        }
+        case 'uninstall': {
+            const scan = scanFlags(tail, UNINSTALL_SCHEMAS);
+            if (scan.error)
+                return usageFail(scan.error);
+            const args = expectArity(scan.literals, 1, 1, 'berry-agent plugins uninstall <id> [--confirm] [--data keep|purge]');
+            if ('exitCode' in args)
+                return args;
+            const dataRaw = scan.values.get('data');
+            return finish(scan, {
+                kind: 'plugins',
+                sub: {
+                    sub: 'uninstall',
+                    id: args[0],
+                    confirm: scan.booleans.has('confirm'),
+                    dataAction: dataRaw === undefined ? undefined : dataRaw,
+                },
+            });
+        }
+        case 'mount':
+        case 'unmount':
+        case 'toggle':
+        case 'update': {
+            const scan = scanFlags(tail, []);
+            if (scan.error)
+                return usageFail(scan.error);
+            const args = expectArity(scan.literals, 1, 1, `berry-agent plugins ${head} <id>`);
+            if ('exitCode' in args)
+                return args;
+            return finish(scan, { kind: 'plugins', sub: { sub: head, id: args[0] } });
+        }
+        default:
+            return usageFail(`未知 plugins 子命令：${head}（合法：list/install/uninstall/mount/unmount/toggle/update/check）`);
+    }
+}
+/** 解析 sessions 子命令段 */
+function parseSessions(rest) {
+    const [head, ...tail] = rest;
+    if (head === undefined || head.startsWith('--')) {
+        return usageFail('sessions 须带子命令（list/resume/fork/search/reindex）');
+    }
+    const zeroArg = head === 'list' || head === 'reindex';
+    const oneArg = head === 'resume' || head === 'fork' || head === 'search';
+    if (!zeroArg && !oneArg) {
+        return usageFail(`未知 sessions 子命令：${head}（合法：list/resume/fork/search/reindex）`);
+    }
+    const scan = scanFlags(tail, []);
+    if (scan.error)
+        return usageFail(scan.error);
+    const usage = zeroArg
+        ? `berry-agent sessions ${head}`
+        : `berry-agent sessions ${head} <${head === 'search' ? 'query' : 'id'}>`;
+    const args = expectArity(scan.literals, zeroArg ? 0 : 1, zeroArg ? 0 : 1, usage);
+    if ('exitCode' in args)
+        return args;
+    if (zeroArg)
+        return finish(scan, { kind: 'sessions', sub: { sub: head } });
+    return finish(scan, {
+        kind: 'sessions',
+        sub: head === 'search'
+            ? { sub: 'search', query: args[0] }
+            : { sub: head, id: args[0] },
+    });
+}
+/** credentials 子命令族解析（03 §10.9 人面命令 CLI 面——c-5；namespace 值域执法归命令件单源，本层只执法解析律） */
+const NAMESPACE_FLAG = { name: 'namespace', kind: 'value' };
+function parseCredentials(rest) {
+    const [head, ...tail] = rest;
+    if (head === undefined || head.startsWith('--')) {
+        return usageFail('credentials 须带子命令（add/list/rm）');
+    }
+    const namespaceOf = (scan) => scan.values.has('namespace') ? scan.values.get('namespace') : undefined;
+    switch (head) {
+        case 'list': {
+            const scan = scanFlags(tail, []);
+            if (scan.error)
+                return usageFail(scan.error);
+            const arity = expectArity(scan.literals, 0, 0, 'berry-agent credentials list');
+            if ('exitCode' in arity)
+                return arity;
+            return finish(scan, { kind: 'credentials', sub: { sub: 'list' } });
+        }
+        case 'add': {
+            const scan = scanFlags(tail, [NAMESPACE_FLAG]);
+            if (scan.error)
+                return usageFail(scan.error);
+            const args = expectArity(scan.literals, 2, 2, 'berry-agent credentials add <name> <value> [--namespace <ns>]');
+            if ('exitCode' in args)
+                return args;
+            const ns = namespaceOf(scan);
+            return finish(scan, {
+                kind: 'credentials',
+                sub: {
+                    sub: 'add',
+                    name: args[0],
+                    value: args[1],
+                    ...(ns !== undefined ? { namespace: ns } : {}),
+                },
+            });
+        }
+        case 'rm': {
+            const scan = scanFlags(tail, [NAMESPACE_FLAG]);
+            if (scan.error)
+                return usageFail(scan.error);
+            const args = expectArity(scan.literals, 1, 1, 'berry-agent credentials rm <name> [--namespace <ns>]');
+            if ('exitCode' in args)
+                return args;
+            const ns = namespaceOf(scan);
+            return finish(scan, {
+                kind: 'credentials',
+                sub: { sub: 'rm', name: args[0], ...(ns !== undefined ? { namespace: ns } : {}) },
+            });
+        }
+        default:
+            return usageFail(`未知 credentials 子命令：${head}（合法：add/list/rm）`);
+    }
+}
+/**
+ * doors 子命令族解析（03 §4.6 / 07 §5 定名——CLI 面；g-2）：list 受理、
+ * open/close 受理为合法解析形（语义拒退 1 归执行层 runDoorsEntry——用法错
+ * 与语义拒两档分立）；值域执法归段编辑腿单源（plugin-store），本层只执法
+ * 解析律。
+ */
+function parseDoors(rest) {
+    const [head, ...tail] = rest;
+    if (head === undefined || head.startsWith('--')) {
+        return usageFail('doors 须带子命令（list/open/close——open/close 写动词 TUI /doors 专属，CLI 只读 list）');
+    }
+    switch (head) {
+        case 'list': {
+            const scan = scanFlags(tail, []);
+            if (scan.error)
+                return usageFail(scan.error);
+            const arity = expectArity(scan.literals, 0, 0, 'berry-agent doors list');
+            if ('exitCode' in arity)
+                return arity;
+            return finish(scan, { kind: 'doors', sub: { sub: 'list' } });
+        }
+        case 'open':
+        case 'close': {
+            const scan = scanFlags(tail, []);
+            if (scan.error)
+                return usageFail(scan.error);
+            const args = expectArity(scan.literals, 1, 1, `berry-agent doors ${head} <capability>`);
+            if ('exitCode' in args)
+                return args;
+            return finish(scan, { kind: 'doors', sub: { sub: head, door: args[0] } });
+        }
+        default:
+            return usageFail(`未知 doors 子命令：${head}（合法：list/open/close）`);
+    }
+}
+/** 收尾统一口：help/version 越位短路（执法④——在一切解析错误之后） */
+function finish(scan, command) {
+    if (scan.overreach === '--help')
+        return { ok: true, command: { kind: 'help', overreach: scan.overreach } };
+    if (scan.overreach === '--version')
+        return { ok: true, command: { kind: 'version', overreach: scan.overreach } };
+    return { ok: true, command };
+}
+/* ---------------- 主入口 ---------------- */
+/**
+ * 解析进程 argv（不含 argv[0]/argv[1]——调用方传 process.argv.slice(2)）。
+ *
+ * 分派序：首词 ∈ 子命令集 → 各命令解析器；首词以 `--` 起头或空 → TUI 入口
+ * （位置参数非空即退 2——无参 TUI 不收位置参数）；其余非旗标首词 → 未知子命令
+ * 退 2。
+ */
+export function parseCli(argv) {
+    const [head, ...rest] = argv;
+    if (head === undefined || head.startsWith('--')) {
+        const leading = head === undefined ? [] : [head];
+        const scan = scanFlags([...leading, ...rest], TUI_SCHEMAS);
+        if (scan.error)
+            return usageFail(scan.error);
+        const arity = expectArity(scan.literals, 0, 0, 'berry-agent（无参 = TUI 主入口；脚本化用 run/serve）');
+        if ('exitCode' in arity)
+            return arity;
+        const port = scan.values.get('port');
+        const command = {
+            kind: 'tui',
+            flags: {
+                port: port === undefined ? undefined : Number(port),
+                noPlugins: scan.booleans.has('no-plugins'),
+                debug: scan.booleans.has('debug'),
+                pluginFile: scan.values.get('plugin-file'),
+            },
+        };
+        return finish(scan, command);
+    }
+    switch (head) {
+        case 'run':
+            return parseRun(rest);
+        case 'serve': {
+            // serve status / serve stop 管理动词（零旗标面——单活跃机只读豁免）
+            const [sub, ...tail] = rest;
+            if (sub === 'status' || sub === 'stop') {
+                const scan = scanFlags(tail, []);
+                if (scan.error)
+                    return usageFail(scan.error);
+                const arity = expectArity(scan.literals, 0, 0, `berry-agent serve ${sub}`);
+                if ('exitCode' in arity)
+                    return arity;
+                return finish(scan, { kind: sub === 'status' ? 'serve-status' : 'serve-stop' });
+            }
+            return parseServe(rest);
+        }
+        case 'mcp': {
+            const scan = scanFlags(rest, []);
+            if (scan.error)
+                return usageFail(scan.error);
+            const arity = expectArity(scan.literals, 0, 0, 'berry-agent mcp');
+            if ('exitCode' in arity)
+                return arity;
+            return finish(scan, { kind: 'mcp' });
+        }
+        case 'dump-config': {
+            const scan = scanFlags(rest, DUMP_SCHEMAS);
+            if (scan.error)
+                return usageFail(scan.error);
+            // --plugin-file 互斥（03 §7 不变式 7）：:memory: 同构诊断须呈现真实
+            // 装载面——试件行注入即诊断保真差；收而互斥拒（非未识别拒——message
+            // 指向互斥根因而非「拼错旗标」）
+            if (scan.values.has('plugin-file')) {
+                return usageFail('--plugin-file 与 dump-config 互斥（诊断保真：:memory: 面须呈现真实装载形，不注入试件行）');
+            }
+            const arity = expectArity(scan.literals, 0, 0, 'berry-agent dump-config');
+            if ('exitCode' in arity)
+                return arity;
+            const port = scan.values.get('port');
+            const command = {
+                kind: 'dump-config',
+                flags: {
+                    port: port === undefined ? undefined : Number(port),
+                    noPlugins: scan.booleans.has('no-plugins'),
+                    debug: scan.booleans.has('debug'),
+                },
+            };
+            return finish(scan, command);
+        }
+        case 'plugins':
+            return parsePlugins(rest);
+        case 'sessions':
+            return parseSessions(rest);
+        case 'credentials':
+            return parseCredentials(rest);
+        case 'doors':
+            return parseDoors(rest);
+        case 'upgrade': {
+            const scan = scanFlags(rest, [DEBUG_FLAG]);
+            if (scan.error)
+                return usageFail(scan.error);
+            const arity = expectArity(scan.literals, 0, 0, 'berry-agent upgrade');
+            if ('exitCode' in arity)
+                return arity;
+            return finish(scan, { kind: 'upgrade' });
+        }
+        default:
+            return usageFail(`未知子命令：${head}（合法：run/serve/mcp/dump-config/plugins/sessions/credentials/doors/upgrade；无参 = TUI 主入口）`);
+    }
+}

package/dist/host/codes.js

@@ -0,0 +1,120 @@
+/**
+ * host 域错误码补落——`PLUGIN_` 族装载面码（02 §5.3 前缀族明列；语义真源 03 篇）
+ * + `TRIGGER_` 族两码（2026-09-07 触发器面 C 批补入——module 段 host 落码定形，
+ * 语义真源 03 §2.2/§2.7 触发器行）。
+ *
+ * 注册纪律：import 发生才注册（与 tools/llm/session 的 codes.ts 同款）；
+ * 同码重复注册由 contracts 注册表 fail-loud 执法（HOST_ERROR_CODE_CONFLICT）。
+ * `PLUGIN_SHAPE_INVALID` 与 `API_` 族四码已随 contracts 首批/API 治理批在册，
+ * 本处不重复注册。
+ *
+ * 批 12d 补落挂账两码：import 门禁越界拒载（03 §3.3 定名
+ * `PLUGIN_IMPORT_FORBIDDEN`——字面量腿 throw 形执法 + fsCache 关；动态构造
+ * 逃逸残差随沙箱立题，详 03 §3.3 批 12d 勘正段）与库句柄门禁（03 §4.3 定名
+ * `PLUGIN_DB_HANDLE_FORBIDDEN`——宿主主库句柄结构性不外露；执法位 =
+ * `berry-agent/sqlite` 虚拟键受局面 SqliteFace，face 件随其落码批消费本码）。
+ *
+ * 2026-09-09 装机面落码批（成熟度缺口 #10）补两码：`PLUGIN_INSTALL_FAILED`
+ * （三源执行器统一失败档）与 `PLUGIN_UNINSTALL_REFUSED`（清算防线拒绝档）
+ * ——02 §5.3 PLUGIN_ 族同笔入册。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+/** 批 12a 补落的 PLUGIN_ 族码目录（语义真源逐条注） */
+export const HOST_PLUGIN_ERROR_CODES = [
+    {
+        code: 'PLUGIN_CONFIG_INVALID',
+        module: 'host',
+        description: '启用行 config 值不合清单 config schema（03 篇 §1.2——装载期拒绝式）',
+    },
+    {
+        code: 'PLUGIN_ROW_INVALID',
+        module: 'host',
+        description: '启用清单行 schema 违例：未知键/id 缺席或坏形（03 篇 §5.3——行校验拒绝式）',
+    },
+    {
+        code: 'PLUGIN_APPLY_FAILED',
+        module: 'host',
+        description: '插件 apply 入口抛错（03 篇 §1.3——处置按 /reload 失败三档行级隔离）',
+    },
+    {
+        code: 'PLUGIN_INJECT_UNRESOLVED',
+        module: 'host',
+        description: '硬依赖（inject）求值后服务缺席拒启（03 篇 §1.3——软依赖缺席仅记 warn）',
+    },
+    {
+        code: 'PLUGIN_ENTRY_UNRESOLVED',
+        module: 'host',
+        description: '入口模块解析失败：entry 指向文件不存在/不可解析（03 篇 §1.3）',
+    },
+    {
+        code: 'PLUGIN_LOAD_FAILED',
+        module: 'host',
+        description: 'jiti 装载失败：语法错误/运行时顶层抛错（03 篇 §1.3）',
+    },
+    {
+        code: 'PLUGIN_RATE_LIMITED',
+        module: 'host',
+        description: '装载器频率护栏：单插件注册/事件动作 >1000 次/1000ms 即拒（03 篇 §3.4）',
+    },
+    {
+        code: 'PLUGIN_EVENT_TYPE_CONFLICT',
+        module: 'host',
+        description: 'durable 事件词汇撞名拒注册：撞 LIVE 词表既有词汇即拒（03 篇 §2.7 逐动词冲突律——词法身份面拒绝式）',
+    },
+    {
+        code: 'PLUGIN_PROMPT_SLOT_INVALID',
+        module: 'host',
+        description: '提示词段 slot 非法：非域前缀两段式/域前缀不等于本插件 id（03 篇 §2.7——无 / 单段系宿主自留地不可达）',
+    },
+    {
+        code: 'PLUGIN_PROMPT_SECTION_CONFLICT',
+        module: 'host',
+        description: '提示词段同 slot 重复注册：两段同位即装配冲突响亮失败（03 篇 §2.7——不静默覆盖）',
+    },
+    {
+        code: 'PLUGIN_HOOK_UNKNOWN',
+        module: 'host',
+        description: 'hookName 不在钩子主表即拒订阅：fail-closed，未知钩子不静默吞（03 篇 §2.4/§2.7）',
+    },
+    {
+        code: 'PLUGIN_WINDOW_CLOSED',
+        module: 'host',
+        description: '装载窗口外调用注册动词拒（03 篇 §2.1——唯一例外：宿主回调上下文内〔钩子 handler/工具执行期〕合法，装载器以回调窗重入计数开合）',
+    },
+    {
+        code: 'PLUGIN_IMPORT_FORBIDDEN',
+        module: 'host',
+        description: 'import 门禁越界拒载：依赖图说明符不在三道白名单（虚拟键/node: 内建/插件目录树内——03 §3.3；字面量腿 transform 钩子 throw 形执法〔error 通道不抛已实证〕+ jiti fsCache 关；门禁定位 = 架构边界非反恶意沙箱，动态构造逃逸残差随沙箱立题）',
+    },
+    {
+        code: 'PLUGIN_DB_HANDLE_FORBIDDEN',
+        module: 'host',
+        description: '库句柄门禁：违例触达宿主主库句柄（主库句柄结构性不外露——03 §4.3；执法位 = berry-agent/sqlite 受局面 SqliteFace，随 face 件落码批消费）',
+    },
+    {
+        code: 'PLUGIN_CAPABILITY_DOOR_CLOSED',
+        module: 'host',
+        description: '高危面默认关拒：插件未获用户开门授予即触达高危面注册/换装（03 §4.6 用户主权开门制——授予位唯一正门 = 启用清单行 opens；裁决核 = contracts adjudicateCapabilityDoor，throw 位随界面后端换装缝/路由受理面落码批接线）',
+    },
+    {
+        code: 'PLUGIN_INSTALL_FAILED',
+        module: 'host',
+        description: '装机执行失败：三源执行器 spawn 非零/收割抛错/ref 与 env 坏形统一档（03 §5.4——成熟度缺口 #10 装机面落码批；失败回滚不留半装机残影）',
+    },
+    {
+        code: 'PLUGIN_UNINSTALL_REFUSED',
+        module: 'host',
+        description: '卸载清算防线拒绝档：删除目标逸出装机子树/插件数据子目录（assertInsideInstallSubtree/assertInsidePluginData——03 §5.5 段②③），或坏账本拒写防覆盖',
+    },
+    {
+        code: 'TRIGGER_NAME_EXISTS',
+        module: 'host',
+        description: '触发器撞名拒：name 撞既有在册触发器（含 issue 件 core: 域）——词法身份面拒绝式，审计归因面重影即歧义（03 §2.7；2026-09-07 触发器面 C 批锚定，执法随 C-2 注册面接线）',
+    },
+    {
+        code: 'TRIGGER_NAME_INVALID',
+        module: 'host',
+        description: '触发器名词法违例拒：name 非域名两段式或域前缀 ≠ 本插件 id（core: 件去前缀取 name 段——防跨插件冒名，03 §2.7 registerSection 行同法；2026-09-07 触发器面 C 批锚定，执法随 C-2 注册面接线）',
+    },
+];
+registerErrorCodes(HOST_PLUGIN_ERROR_CODES);