@stalfh233/omc-cli 0.0.0-stage → 0.4.0

package/dist/cli.js

@@ -0,0 +1,1418 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { stdin, argv, exit } from "node:process";
+import { Command, CommanderError } from "commander";
+import { ConfigStore, defaultPaths, removedProfileKeys } from "./config-store.js";
+import { loadCoverageManifest, versionFamilyNotice } from "./coverage.js";
+import { redactText } from "./redact.js";
+import { readArgsFile, readStdinArgs, runToolCall, validateAgentPaths } from "./call.js";
+import { environmentWritable, requiresProductionConfirmation } from "./environment-policy.js";
+import { CLI_EXIT_CODES, classifyResult, envelope, errorEnvelope, requestId } from "./cli-contract.js";
+import { configureOutput, humanSummary, stripOutputFlags, writeEnvelope } from "./cli-output.js";
+import { beginUsage, completeUsage, usageReport } from "./usage-log.js";
+import { artifactFetchHint, artifactRoot, boundResult, emitInvalid, emitResult, emitTransportResult, outputBudget, readArtifact, withTransport, } from "./command-transport.js";
+import { CLI_DEFAULT_OUTPUT_BYTES, assertSafeOutputPath, createArtifact } from "./artifacts.js";
+import { jsonBytes, sha256, writeArtifact } from "./support.js";
+import { join, resolve } from "node:path";
+import { writeFileSync } from "node:fs";
+import { buildToolRegistry } from "./tools.js";
+import { acquireWriteLock } from "./write-lock.js";
+import { commandIndex, commandInventory, describeContract, describeContractFull, describeContractTool, describeExample, describeParam, describeSchemaOnly, describeTool, describeToolFull } from "./discovery.js";
+import { buildCapabilityOverview, capabilityDetail, compactCapabilities, executableCapabilityBundle, resolveCapabilityId, DISCOVERY_AUTHORITY } from "./capability-overview.js";
+import { goalRoute } from "./goal-routes.js";
+import { absencePointer } from "./capability-absences.js";
+import { intentConfigRoot, readIntentFile, validateIntentText, INTENT_COMPILER_VERSION } from "./intent/cli.js";
+import { intentSchemaBlock, intentExample, intentExampleIds } from "./intent/schema.js";
+import { baselineFingerprintOf, readBaseline } from "./intent/baseline.js";
+import { compileIntent } from "./intent/compiler.js";
+import { expectedRuleGraph } from "./intent/capabilities/businessrule.js";
+import { validateRuleNodeGraph, PLATFORM_TRIGGER_RULE_CODES, walkConditionLeaves } from "./lanes/rule-graph.js";
+import { buildPlan, verifyPlan } from "./intent/plan-file.js";
+import { compareWithLive, decodeBaseline } from "./intent/readback.js";
+import { listSkills, readSkill, readSkillSection } from "./skills.js";
+import { parseToolInput, ToolInputError, ToolRefusalError } from "./tool-types.js";
+import { WireError, wireCall } from "./wire.js";
+import { ENDPOINTS } from "./endpoints.js";
+import { makeToolContext } from "./context.js";
+import { SessionManager } from "./session-manager.js";
+async function ask(question) {
+    const rl = createInterface({ input: stdin, output: process.stderr });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Hidden password prompt (no echo). */
+async function askSecret(question) {
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: stdin, output: process.stderr, terminal: true });
+    const writeOutput = rl._writeToOutput.bind(rl);
+    rl._writeToOutput = (text) => {
+        if (text.includes(question))
+            writeOutput(text);
+    };
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+async function cmdSetup(store, args) {
+    const flag = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 ? args[index + 1] : undefined;
+    };
+    if (args.includes("--list")) {
+        for (const { name, profile } of store.listEnvironments())
+            console.error(`${name}${profile.isDefault ? "（默认）" : ""} [${profile.production ? "生产环境" : "测试环境"}，${environmentWritable(profile) ? "允许写入" : "只读"}${profile.production ? "（生产写需逐笔 confirmProduction）" : ""}${removedProfileKeys(profile).length > 0 ? `，⚠ 含已移除键：${removedProfileKeys(profile).join("、")}` : ""}] -> ${profile.baseUrl} 应用=${profile.applicationCode}${profile.engineCode ? ` 租户=${profile.engineCode}` : ""}`);
+        return 0;
+    }
+    const editName = flag("--edit");
+    const removeName = flag("--remove");
+    if (removeName) {
+        store.removeEnvironment(removeName);
+        console.error(`已删除环境 ${removeName}`);
+        return 0;
+    }
+    let name = editName ?? (await ask("环境名称（例如 test）：")).trim();
+    if (!name) {
+        const fallback = store.listEnvironments().find((entry) => entry.profile.isDefault);
+        if (!fallback) {
+            console.error("必须填写环境名称（当前没有默认环境可回退）");
+            return 1;
+        }
+        name = fallback.name;
+        console.error(`未输入名称，改为编辑默认环境 ${name}（用 --list 查看全部，用 --edit <环境> 选择其它）`);
+    }
+    const previous = store.readConfig().environments[name];
+    const baseUrl = (await ask(`CloudPivot 服务地址${previous ? ` [${previous.baseUrl}]` : ""}：`)).trim() || previous?.baseUrl;
+    const applicationCode = (await ask(`默认应用 code（可选，留空则由 Agent 运行时发现应用）${previous?.applicationCode ? ` [${previous.applicationCode}]` : ""}：`)).trim() || previous?.applicationCode || "";
+    const engineCode = (await ask(`多租户 engineCode（可选；仅当网关按 x-lowcode-enginecode 路由、不带则 404 时填写，留空为单租户）${previous?.engineCode ? ` [${previous.engineCode}]` : ""}：`)).trim() || previous?.engineCode || "";
+    const username = (await ask(`登录账号${previous ? " [保留已存账号]" : ""}：`)).trim();
+    const password = username ? await askSecret("登录密码（输入不回显，以 0600 存储，绝不外泄）：") : "";
+    const defaultAnswer = (await ask(`设为默认环境？[y/N]${previous?.isDefault ? "（当前已是默认）" : ""}：`)).trim().toLowerCase();
+    const isDefault = defaultAnswer ? defaultAnswer === "y" : previous?.isDefault === true;
+    const productionAnswer = (await ask(`这是生产环境吗？（风险标签：生产写入每次都要显式高危确认，但仍由 writable 决定能否写）[y/N]${previous?.production ? "（当前是生产）" : ""}：`)).trim().toLowerCase();
+    const production = productionAnswer ? productionAnswer === "y" : previous?.production === true;
+    const writableAnswer = (await ask(`允许在这个环境执行新增、修改、删除和发布吗？（唯一的写入开关）[y/N]${environmentWritable(previous ?? { baseUrl: "", applicationCode: "", production }) ? "（当前允许写入）" : "（当前只读）"}：`)).trim().toLowerCase();
+    const writable = writableAnswer ? writableAnswer === "y" : previous?.writable ?? false;
+    store.upsertEnvironment(name, {
+        baseUrl,
+        applicationCode,
+        ...(engineCode ? { engineCode } : {}),
+        ...(isDefault ? { isDefault: true } : {}),
+        production,
+        writable,
+    });
+    if (username && password)
+        store.writeCredential(name, { username, password });
+    const bind = (await ask("将本项目（.omc-env）绑定到该环境？[y/N]：")).toLowerCase() === "y";
+    if (bind)
+        store.bindProjectEnvironment(name);
+    console.error(`环境 ${name} 已保存（幂等，可随时重跑 omc setup）。凭据存储模式：${store.credentialsMode()}`);
+    return 0;
+}
+async function cmdDoctor(store, environment) {
+    const manifest = loadCoverageManifest();
+    const steps = [];
+    let ok = true;
+    try {
+        const resolved = store.resolveEnvironment(environment);
+        steps.push(`配置      ok  环境=${resolved.name}（来源 ${resolved.source}）`);
+        steps.push(`写入      ok  写入=${environmentWritable(resolved.profile) ? "允许" : "只读"}${requiresProductionConfirmation(resolved.profile) ? "；生产环境：每笔写入需 confirmProduction" : ""}`);
+        const removed = removedProfileKeys(resolved.profile);
+        if (removed.length > 0)
+            steps.push(`配置      ⚠  含已移除键（请删除）：${removed.join("、")}`);
+        if (resolved.profile.engineCode)
+            steps.push(`租户      ok  多租户 engineCode=${resolved.profile.engineCode}（随每笔请求发 x-lowcode-enginecode）`);
+        const credential = store.readCredential(resolved.name);
+        steps.push(`凭据      ok  模式=${store.credentialsMode()} 账号=${credential.username}`);
+        const { CloudPivotSession } = await import("./session.js");
+        const session = new CloudPivotSession(resolved.name, resolved.profile, credential);
+        await session.login();
+        steps.push(`登录      ok  企业=${session.enterpriseId()} 管理员=${session.administrator()}`);
+        const version = session.detectedVersion();
+        if (!version) {
+            steps.push(`版本      WARN 无版本证据；写入将保守拒绝（fail closed）`);
+        }
+        else {
+            const notice = versionFamilyNotice(manifest, version);
+            if (notice)
+                steps.push(`版本      WARN ${notice}`);
+            else
+                steps.push(`版本      ok  ${version}（族 ${manifest.version_family}，锚点 ${manifest.anchor_version}）`);
+        }
+        steps.push(`环境指纹  ok  ${session.environmentFingerprint()}`);
+        // A CloudPivot license expiry answers 109001 on apppackage/list and turns
+        // the whole surface (most reads and every write) into refusals. Config,
+        // credentials, login, version and fingerprint all still pass, so without
+        // this probe doctor reports "通过" on an environment nothing can operate.
+        try {
+            await wireCall(session, { path: ENDPOINTS.applicationList, query: {} });
+            steps.push(`许可证    ok  平台 apppackage/list 可访问`);
+        }
+        catch (error) {
+            const errcode = error instanceof WireError ? error.errcode : undefined;
+            if (errcode === 109001 || /许可证|license/i.test(error.message)) {
+                ok = false;
+                steps.push(`许可证    FAIL 已过期（平台拒绝 apppackage/list：${String(errcode ?? "")}）——续期或更换环境；否则几乎全部读面与所有写面都会被 109001 拒绝`);
+            }
+            else {
+                ok = false;
+                steps.push(`许可证    FAIL 许可证面探测失败：${redactText(error.message, [])}`);
+            }
+        }
+    }
+    catch (error) {
+        ok = false;
+        steps.push(`自检      FAIL ${redactText(error.message, [])}`);
+    }
+    for (const line of steps)
+        console.error(line);
+    // Cold-start anchor (round 2, module D): `doctor` runs every session, so it
+    // carries the minimal-read path, the artifact convention, and the readiness
+    // command — the facts a first-time agent otherwise assembles from ~52 KB of
+    // prose. Kept terse so the anchor stays ~1 KB.
+    console.error(doctorAnchor());
+    console.error(ok ? "doctor：通过" : "doctor：失败");
+    return ok ? 0 : 1;
+}
+/** The cold-start anchor `doctor` appends: minimal path, artifact convention, readiness. */
+function doctorAnchor() {
+    const topics = listSkills().map((entry) => entry.name).join("、");
+    return [
+        "最小路径  omc next \"<目标>\"（目标→工具一步定位，不确定会明说）→ omc help omc-start-here → omc call discover_environment --env <env> --args '{}'（<env> 名以 doctor 的「环境=」或项目 .omc-env 为准，勿猜）→ omc capabilities / omc describe <tool>",
+        `方法论    omc help <topic> --sections / --section "<标题>"（按节读，随包 skills/）；topic：${topics}`,
+        "大输出    超预算结果只回 artifactId/sha256/fetch；用 fetch 里的 omc artifact get <id>（可加 --jq <path>）取回，勿全量读入",
+    ].join("\n");
+}
+function flag0(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function cmdCall(store, args) {
+    const request = flag0(args, "--request-id") ?? requestId();
+    let maxOutputBytes;
+    try {
+        maxOutputBytes = outputBudget(args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message, retryable: false }));
+        return CLI_EXIT_CODES.invalidInput;
+    }
+    const emit = (status, result, exitCode) => {
+        if (status === "uncertain" && result.nextAction === undefined)
+            result = { ...result, nextAction: "read back the requestId before retrying; retry only after the outcome is established" };
+        const classified = classifyResult(result);
+        writeEnvelope(envelope(status, boundResult(result, maxOutputBytes), request, classified.error));
+        return exitCode;
+    };
+    const flag = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 ? args[index + 1] : undefined;
+    };
+    const positional = args.filter((token, index) => !token.startsWith("--") && (index === 0 || !args[index - 1]?.startsWith("--env") && !args[index - 1]?.startsWith("--environment") && !args[index - 1]?.startsWith("--args")));
+    const toolName = positional[0];
+    if (!toolName || toolName === "help" || args.includes("--help")) {
+        console.error("用法：omc call <tool> [--env <环境>] [--args '<json>' | --args - (stdin) | --args-file <path>]");
+        console.error("写入：由环境 writable 决定（只读环境拒写）；生产环境的写必须在 args 里带 confirmProduction:true。");
+        return emit(toolName && toolName !== "help" ? "error" : "ok", {}, toolName && toolName !== "help" ? CLI_EXIT_CODES.invalidInput : 0);
+    }
+    const environment = flag("--env") ?? flag("--environment");
+    const requestValue = flag("--request-id");
+    const dryRun = args.includes("--dry-run");
+    const waitValue = flag("--wait");
+    let waitMs = 0;
+    if (waitValue !== undefined) {
+        waitMs = Number(waitValue);
+        if (!Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > 600_000) {
+            const message = "--wait must be an integer number of milliseconds from 0 to 600000";
+            writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message, retryable: false }));
+            return CLI_EXIT_CODES.invalidInput;
+        }
+    }
+    let timeoutMs;
+    try {
+        if (requestValue !== undefined && requestValue.length === 0)
+            throw new Error("--request-id must not be empty");
+        const value = flag("--timeout-ms");
+        if (value !== undefined) {
+            timeoutMs = Number(value);
+            if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 600_000)
+                throw new Error("--timeout-ms must be an integer from 1 to 600000");
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message, retryable: false }));
+        return CLI_EXIT_CODES.invalidInput;
+    }
+    if (timeoutMs !== undefined)
+        process.env.OMC_HTTP_TIMEOUT_MS = String(timeoutMs);
+    const rawArgs = flag("--args");
+    const argsFile = flag("--args-file");
+    let parsedArgs = {};
+    try {
+        if (rawArgs !== undefined && argsFile !== undefined)
+            throw new Error("--args and --args-file are mutually exclusive");
+        if (rawArgs === "-")
+            parsedArgs = readStdinArgs();
+        else if (argsFile)
+            parsedArgs = readArgsFile(argsFile, resolve(process.env.OMC_CONFIG_HOME ?? process.cwd()));
+        else if (rawArgs) {
+            parsedArgs = JSON.parse(rawArgs);
+            if (parsedArgs === null || typeof parsedArgs !== "object" || Array.isArray(parsedArgs))
+                throw new Error("--args must be a JSON object");
+        }
+        validateAgentPaths(parsedArgs);
+    }
+    catch (error) {
+        console.error(`--args 必须是合法 JSON：${error instanceof Error ? error.message : String(error)}`);
+        writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message: error instanceof Error ? error.message : String(error), retryable: false }));
+        return CLI_EXIT_CODES.invalidInput;
+    }
+    const registry = buildToolRegistry();
+    const tool = registry.find((definition) => definition.name === toolName);
+    if (tool) {
+        try {
+            parsedArgs = parseToolInput(tool, {
+                ...parsedArgs,
+                ...(environment && parsedArgs.environment === undefined ? { environment } : {}),
+                ...(requestValue !== undefined ? { requestId: requestValue } : {}),
+                ...(dryRun ? { dryRun: true } : {}),
+            });
+        }
+        catch (error) {
+            const result = error instanceof ToolInputError ? error.payload : { status: "error", message: error instanceof Error ? error.message : String(error) };
+            return emit("error", result, CLI_EXIT_CODES.invalidInput);
+        }
+    }
+    const toolKind = tool?.kind;
+    let lock;
+    // A `--dry-run` never mutates the environment: the governed pipeline settles it
+    // before write admission, so it must not contend for the cross-process lock.
+    if (toolKind === "write" && !dryRun) {
+        const lockTarget = environment ?? resolvedDefaultEnvironment(store);
+        const deadline = Date.now() + waitMs;
+        for (;;) {
+            lock = await acquireWriteLock(lockTarget);
+            if (lock.held)
+                break;
+            if (Date.now() >= deadline) {
+                const conflict = {
+                    status: "refused",
+                    blocker: "write-lock-held",
+                    environment: lockTarget,
+                    owner: lock.owner,
+                    recovery: lock.recovery,
+                    message: lock.recovery[0],
+                };
+                console.error(`write lock conflict: ${JSON.stringify(lock.owner)}`);
+                writeEnvelope(envelope("refused", conflict, request, classifyResult(conflict).error));
+                return CLI_EXIT_CODES.policyRefused;
+            }
+            await sleep(Math.min(200, Math.max(0, deadline - Date.now())));
+        }
+    }
+    let timedOut = false;
+    let result;
+    try {
+        ({ result } = await runToolCall(toolName, {
+            args: parsedArgs,
+            ...(environment ? { environment } : {}),
+            ...(requestValue !== undefined ? { requestId: requestValue } : {}),
+            dryRun,
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            print: (line) => humanSummary(line),
+        }));
+        if (result?.status === "uncertain" && result?.blocker === "cli-timeout")
+            timedOut = true;
+    }
+    finally {
+        if (lock?.held) {
+            if (timedOut) {
+                console.error(`cli-timeout: the write may still be in flight; the environment lock is deliberately NOT released — it auto-recovers once pid ${process.pid} exits (stale recovery)`);
+            }
+            else
+                await lock.release();
+        }
+    }
+    const classified = classifyResult(result);
+    return emit(classified.status, result, classified.exitCode);
+}
+function resolvedDefaultEnvironment(store) {
+    try {
+        return store.resolveEnvironment(undefined).name;
+    }
+    catch {
+        return "default";
+    }
+}
+/**
+ * Bounded JSON-path projection for `artifact get --jq`. Supports dotted
+ * (`content.activities.0.name`) and slashed (`content/activities/0/name`)
+ * segments. Not a general jq: a path walk only, so it can never evaluate code.
+ */
+function projectJsonPath(value, path) {
+    const segments = path.replace(/^\//, "").split(/[./]/).filter((segment) => segment.length > 0);
+    let current = value;
+    for (const segment of segments) {
+        if (Array.isArray(current)) {
+            const index = Number(segment);
+            if (!Number.isInteger(index) || index < 0 || index >= current.length)
+                return undefined;
+            current = current[index];
+        }
+        else if (current && typeof current === "object") {
+            const record = current;
+            if (!Object.prototype.hasOwnProperty.call(record, segment))
+                return undefined;
+            current = record[segment];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}
+async function cmdArtifactGet(id, transport, options = {}) {
+    try {
+        const artifact = readArtifact(artifactRoot(), id);
+        let content;
+        try {
+            content = JSON.parse(artifact.content.toString("utf8"));
+        }
+        catch {
+            content = artifact.content.toString("utf8");
+        }
+        // `--path-only` deliberately does NOT return the local path: the Agent-facing
+        // CLI contract forbids exposing local filesystem paths. It returns the fetch
+        // command instead, which is the portable way to reach the body.
+        if (options.pathOnly)
+            return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, fetch: artifactFetchHint(id) }, transport);
+        // `--summary` / `--keys` (round 4): inspect a large artifact without pulling
+        // its whole body. Reproduced benchmark: agents fetched 30–75 KB workflow
+        // bodies just to look at the node list.
+        if (options.summary) {
+            const record = content && typeof content === "object" && !Array.isArray(content) ? content : undefined;
+            const keys = record ? Object.entries(record).map(([key, value]) => ({ key, bytes: Buffer.byteLength(JSON.stringify(value) ?? "null", "utf8"), kind: Array.isArray(value) ? `array[${value.length}]` : value === null ? "null" : typeof value })).sort((left, right) => right.bytes - left.bytes) : [];
+            return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, fetch: artifactFetchHint(id) }, transport);
+        }
+        if (options.keys !== undefined) {
+            // Round 15: tolerate a `result.`/`data.` prefix and report missing keys.
+            // bench63 tried `--keys result.publishedAttributesJson` (empty) before
+            // `--keys publishedAttributesJson` worked; the artifact content IS the
+            // result object, so a leading envelope prefix is a no-op the caller does
+            // not expect. Strip it, and when a key truly is absent list the real
+            // top-level keys so the next call is correct.
+            const wanted = options.keys.split(",").map((key) => key.trim()).filter(Boolean);
+            const record = content && typeof content === "object" && !Array.isArray(content) ? content : undefined;
+            const projected = {};
+            const missing = [];
+            for (const raw of wanted) {
+                const candidates = record === undefined ? [raw] : [raw, raw.replace(/^(result|data)\./, "")];
+                const hit = candidates.find((key) => record !== undefined && key in record);
+                if (hit !== undefined && record !== undefined)
+                    projected[hit] = record[hit];
+                else
+                    missing.push(raw);
+            }
+            const result = { status: "ok", artifactId: id, sha256: artifact.sha256, keys: wanted, ...(missing.length > 0 ? { missingKeys: missing, availableKeys: record ? Object.keys(record) : [] } : {}), content: projected };
+            if (Buffer.byteLength(JSON.stringify(result), "utf8") > transport.maxOutputBytes)
+                return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, projection: options.keys, ...(missing.length > 0 ? { missingKeys: missing, availableKeys: record ? Object.keys(record) : [] } : {}), fetch: artifactFetchHint(id) }, transport);
+            return emitTransportResult(result, transport);
+        }
+        if (options.jq !== undefined) {
+            const projected = projectJsonPath(artifact.content.toString("utf8") === "" ? undefined : content, options.jq);
+            return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: projected === undefined ? null : projected }, transport);
+        }
+        const result = { status: "ok", artifactId: id, sha256: artifact.sha256, content };
+        if (Buffer.byteLength(JSON.stringify(result), "utf8") > transport.maxOutputBytes)
+            return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, fetch: artifactFetchHint(id) }, transport);
+        return emitTransportResult(result, transport);
+    }
+    catch (error) {
+        // Round 16 (bench67 feedback): a missing/expired artifact id is ordinary
+        // caller error, not an internal fault — classify it as invalid-input with a
+        // structured code and a recovery hint instead of a generic `internal`.
+        const message = error instanceof Error ? error.message : String(error);
+        if (message === "artifact not found" || message === "invalid artifact id") {
+            const hint = message === "artifact not found"
+                ? "artifact 不存在或已被清理/过期；用产出它的命令返回的最新 artifactId（结果里的 fetch 提示）重新取，或重跑该命令"
+                : "artifactId 不是合法 UUID（36 位十六进制/连字符）";
+            const parsed = errorEnvelope(new Error(hint), "artifact-absent", CLI_EXIT_CODES.invalidInput, transport.request);
+            writeEnvelope(parsed.envelope);
+            return parsed.exitCode;
+        }
+        const parsed = errorEnvelope(error, "internal", CLI_EXIT_CODES.internal, transport.request);
+        writeEnvelope(parsed.envelope);
+        return parsed.exitCode;
+    }
+}
+async function cmdBench(args) {
+    const liveSample = args.includes("--live-sample");
+    const envIndex = args.indexOf("--env");
+    const liveEnvironment = envIndex >= 0 ? args[envIndex + 1] : undefined;
+    const { runBench, formatBenchReport } = await import("./bench/run.js");
+    const report = await runBench({ mode: liveSample ? "live-sample" : "fake", ...(liveEnvironment ? { liveEnvironment } : {}) });
+    console.error(formatBenchReport(report));
+    const failedSteps = report.steps.filter((step) => !step.ok).length;
+    return failedSteps === 0 && report.dimensions.intent.passed === report.dimensions.intent.cases ? 0 : 1;
+}
+function cmdDiscovery(kind, transport, value, options = {}) {
+    const registry = buildToolRegistry();
+    let result;
+    // Round 16b: `intent` is a CLI subcommand family, not a call tool, so
+    // `describe intent` used to dead-end. Route it (and `intent.schema`) to the
+    // offline DSL schema — the discovery face the dogfood rounds were missing.
+    if (kind === "describe" && (value === "intent" || value === "intent.schema" || value === "intent.validate")) {
+        // Honor `--example <id>` so `describe intent --example rule-actions-when-filter`
+        // returns runnable YAML, mirroring the tool-example UX.
+        if (options.example !== undefined && typeof options.example === "string") {
+            const found = intentExample(options.example);
+            if (!found)
+                return emitInvalid(transport, { message: `intent 示例 id 不存在：${options.example}；可用示例：${intentExampleIds().join("、")}` });
+            return emitTransportResult({ status: "ok", ...found }, transport);
+        }
+        if (value === "intent.validate")
+            return emitTransportResult({ status: "ok", ...intentSchemaBlock(), note: "intent.validate 是子命令，不是工具：见 schema 的 commands；用法 omc intent validate <file>" }, transport);
+        return emitTransportResult({ status: "ok", ...intentSchemaBlock() }, transport);
+    }
+    if (kind === "commands") {
+        const scoped = options.filter !== undefined || options.lane !== undefined;
+        // Bare `commands` is the bounded index (see commandIndex): the full 54 KB
+        // catalogue must be requested with `commands --json` (round-9 heavy-task: an
+        // agent paid 4×54 KB on the default face before any hint could land).
+        if (options.json !== true && options.compact !== true && !scoped) {
+            result = commandIndex(registry);
+            return emitTransportResult({ status: "ok", ...result }, transport);
+        }
+        const inventory = commandInventory(registry, { compact: options.compact === true });
+        // `commands --json` is the programmatic selection entry: filtering server-side
+        // keeps the caller from pulling the whole >50 KB inventory to find one lane.
+        if (options.filter !== undefined || options.lane !== undefined) {
+            const tools = inventory.tools;
+            const keyword = options.filter?.toLowerCase();
+            const matched = tools.filter((tool) => {
+                if (options.lane !== undefined && tool.lane !== options.lane)
+                    return false;
+                if (keyword === undefined)
+                    return true;
+                return `${tool.name} ${tool.lane ?? ""} ${JSON.stringify(tool.capability ?? "")}`.toLowerCase().includes(keyword);
+            });
+            inventory.filtered = { filter: options.filter ?? null, lane: options.lane ?? null, matched: matched.length, total: tools.length };
+            inventory.tools = matched;
+            // A filtered query wants tool rows, not the whole catalogue's discovery,
+            // skills, and intent prose. Keep only the authoritative route pointer.
+            delete inventory.skills;
+            delete inventory.intent;
+            const discovery = inventory.discovery;
+            if (discovery)
+                inventory.discovery = { authoritative: discovery.authoritative, route: discovery.route };
+        }
+        result = inventory;
+    }
+    else if (kind === "contract") {
+        if (options.tool !== undefined) {
+            if (options.full)
+                return emitInvalid(transport, { message: "--tool and --full are mutually exclusive: --tool returns one tool's slice; --full returns the whole lane contract" });
+            const sliced = describeContractTool(registry, value ?? "", options.tool);
+            if (!sliced)
+                return emitInvalid(transport, { message: `contract target not found: lane ${value ?? ""}` });
+            const contract = sliced.contract;
+            if (contract.found === false)
+                return emitInvalid(transport, { message: `lane ${value ?? ""} has no tool "${options.tool}"; available: ${contract.available.join("、")}` });
+            result = sliced;
+        }
+        else {
+            result = options.full ? describeContractFull(registry, value ?? "") : describeContract(registry, value ?? "");
+        }
+    }
+    else if (options.schemaOnly)
+        result = describeSchemaOnly(registry, value ?? "");
+    else if (options.param)
+        result = describeParam(registry, value ?? "", options.param);
+    else if (options.example !== undefined)
+        result = describeExample(registry, value ?? "", typeof options.example === "string" ? options.example : undefined);
+    else if (options.full)
+        result = describeToolFull(registry, value ?? "");
+    else
+        result = describeTool(registry, value ?? "");
+    if (!result) {
+        // Name the closest candidates so a near-miss tool name does not cost a
+        // guess-and-retry call (round-4 dogfood: `form.create` / `data.create` /
+        // `model.list` each burned a call before the agent found the real tool).
+        const requested = value ?? "";
+        // Runtime approval has no dedicated tool: an agent asking for
+        // `workitem.approve` / `workflow.start` / `workitem.submit` dead-ends on the
+        // nearest tool and burns a round. Name the real path (round 15 dogfood).
+        const approvalIntent = /^(workflow|workitem)\.(start|approve|reject|submit|pass|complete|workitem)/i.test(requested) || /approv/i.test(requested);
+        const approvalPointer = approvalIntent
+            ? `；运行时审批/流程推进没有独立工具——查待办用 \`omc call workitem.list\`（拿 workItemId/workflowInstanceId/bizObjectId），提交/审批用 \`omc call data.submit\`（formType=1 + workItemId + workflowInstanceId + bizObjectId + formData；同意传 agree:true）。data.submit 成功后 readback.nextSubmit 会给出下一步审批参数（若仍有待办）；逐级审批无需重复调用 workitem.list。示例形状：describe data.submit --example workflow-backed-data-submit`
+            : "";
+        // `intent.*` is a CLI subcommand namespace, not a tool: an agent asking for
+        // `describe intent.validate` dead-ends. Point at the real subcommands.
+        const intentPointer = /^intent[._\/]/i.test(requested)
+            ? `；intent 是 CLI 子命令，不是 call 工具——用 \`omc intent validate <file> [--show-intent]\`、\`omc intent plan <file> --env <env>\`、\`omc intent apply <planFile>\`、\`omc intent readback <file> --env <env>\`（用法见 omc help omc-start-here --section "声明式意图"）`
+            : "";
+        // `form.get_published` / `form.draft_get` are natural guesses but there is ONE
+        // form read face: `form.get` (its result carries both draft and published
+        // faces; `published:true` narrows). Name it so the guess costs no retry.
+        const formPointer = /^form\./i.test(requested) && requested !== "form.get"
+            ? `；表单只有 \`form.get\` 一个读面：结果同时含 draft/published（publishedAttributesJson 等）；要只看发布态用 \`omc call form.get --args '{"schemaCode":"…","published":true}'\``
+            : "";
+        // Accept a hyphen/underscore alias for a dotted namespace too: a subagent that
+        // asks for `describe rule-graph` (a methodology/template name, not a tool)
+        // should at least get the real `rule.*` tools back instead of a dead end.
+        const segment = requested.split(/[.\-_/]/)[0] ?? requested;
+        const candidates = registry
+            .map((tool) => tool.name)
+            .filter((name) => name === segment || name.startsWith(`${segment}.`) || name.includes(requested))
+            .slice(0, 8);
+        const pointer = candidates.length === 0 && (kind === "describe" || kind === "contract")
+            ? `；describe 的目标是工具名（如 rule.save）；图/模板/节点形状用 describe <tool> --full 或 contract <lane>，工具清单用 omc next "<目标>" / omc commands --json --compact`
+            : "";
+        const absence = absencePointer(requested);
+        return emitInvalid(transport, { message: `${kind} target not found: "${requested}"${candidates.length > 0 ? `; did you mean: ${candidates.join("、")}` : ""}${absence}${approvalPointer}${intentPointer}${formPointer}${pointer}` });
+    }
+    return emitTransportResult({ status: "ok", ...result }, transport);
+}
+function cmdUsage(transport) {
+    return emitTransportResult(usageReport(), transport);
+}
+/**
+ * Round 3, module A — `omc next "<goal>"`: the goal → route solver. Read-only,
+ * zero environment contact; a deterministic projection of authored metadata.
+ */
+function cmdNext(goal, transport) {
+    const result = goalRoute(buildToolRegistry(), goal);
+    return emitTransportResult(result, transport);
+}
+/**
+ * Ticket 125 — `omc capabilities` / `omc capability <id>`: the Configuration
+ * capability overview. Read-only, zero environment contact; a projection of
+ * the tool registry, the coverage manifest, and the intent capability registry.
+ */
+function cmdCapabilities(transport) {
+    const result = compactCapabilities(buildToolRegistry());
+    return emitTransportResult({ status: "ok", ...result }, transport);
+}
+function cmdCapability(id, transport, executable = false) {
+    const registry = buildToolRegistry();
+    const resolved = resolveCapabilityId(id);
+    if (!resolved) {
+        const available = buildCapabilityOverview(registry).map((entry) => entry.id).join("、");
+        return emitInvalid(transport, { message: `未知 capability "${id}"；合法取值：${available}（清单见 omc capabilities）` });
+    }
+    if (executable) {
+        const bundle = executableCapabilityBundle(registry, resolved);
+        if (!bundle)
+            return emitInvalid(transport, { message: `capability "${id}" 没有可执行 bundle` });
+        return emitResult({ status: "ok", capability: bundle }, transport);
+    }
+    return emitResult({ status: "ok", capability: capabilityDetail(registry, resolved) }, transport);
+}
+/**
+ * Read + validate an intent file, or emit the shared invalid-input envelope.
+ * The intent commands (validate / plan / readback) share this preamble.
+ */
+function readIntentOrInvalid(file, transport) {
+    let outcome;
+    try {
+        outcome = validateIntentText(readIntentFile(intentConfigRoot(), file));
+    }
+    catch (error) {
+        return { kind: "exit", code: emitInvalid(transport, { message: error instanceof Error ? error.message : String(error) }) };
+    }
+    if (!outcome.valid || outcome.intent === undefined) {
+        for (const error of outcome.errors)
+            console.error(`intent ${file}:${error.line}:${error.column} [${error.code}] ${error.message}`);
+        writeEnvelope(envelope("error", { status: "error", valid: false, errors: outcome.errors }, transport.request, {
+            code: "invalid-input",
+            message: outcome.errors[0]?.message ?? "intent invalid",
+            retryable: false,
+        }));
+        return { kind: "exit", code: CLI_EXIT_CODES.invalidInput };
+    }
+    return { kind: "ok", intent: outcome.intent };
+}
+/**
+ * Compact confirmation of a valid intent: which models/fields/rules the DSL
+ * normalized to, WITHOUT echoing the whole parsed intent (round 15). The caller
+ * authored the file, so repeating every name/type/option back is redundant —
+ * bench45 charged ~3.3 KB × 7 validate calls. `--show-intent` restores the full
+ * echo when a caller genuinely wants the normalized shape.
+ */
+function intentDigest(intent) {
+    return {
+        intentVersion: intent.intentVersion,
+        models: intent.models.map((model) => ({
+            code: model.code,
+            ...(model.absent ? { absent: true } : {}),
+            fieldCodes: model.fields.map((field) => field.code),
+            ...(model.fields.some((field) => field.subFields !== undefined)
+                ? { subFieldCodes: Object.fromEntries(model.fields.filter((field) => field.subFields !== undefined).map((field) => [field.code, (field.subFields ?? []).map((sub) => sub.code)])) }
+                : {}),
+            ...(model.datarules !== undefined ? { datarulePropertyCodes: model.datarules.map((rule) => rule.propertyCode) } : {}),
+            ...(model.rules !== undefined ? { ruleCodes: model.rules.map((rule) => rule.code) } : {}),
+            ...(model.form !== undefined ? { form: true } : {}),
+            ...(model.listview !== undefined ? { listview: true } : {}),
+            ...(model.workflow !== undefined ? { workflow: true } : {}),
+            ...(model.onlinejs !== undefined ? { onlinejs: true } : {}),
+        })),
+        ...(intent.services !== undefined ? { serviceCodes: intent.services.map((service) => service.code) } : {}),
+        ...(intent.reports !== undefined ? { reportCodes: intent.reports.map((report) => report.code) } : {}),
+    };
+}
+/**
+ * Warning-severity findings the declarative face must not swallow. The rule
+ * dry-lint computes warnings (e.g. `rule-graph-cross-model-unverified`: a
+ * cross-model UPDATE saves+publishes but was observed to write nothing at
+ * runtime — bench50/52/53/55); `validateRuleNodeGraph` is the single source, so
+ * this reuses it rather than re-deriving semantics.
+ */
+function intentWarnings(intent) {
+    const warnings = [];
+    for (const model of intent.models) {
+        // Field-level data rules of type 3/4/5 (拼接/必填/只读) are PORTAL-FACING, but
+        // the platform stores them as bizdatarule rows and mirrors them only into the
+        // form control's `historyOpt` — while the runtime portal reads the control's
+        // `options`. So a datarule-only required/readonly renders/stays inert in the
+        // portal (live 2026-09-28: bench62 datarule type4 on order_note, published
+        // control had no requiredFormula; the live portal did not require it). The
+        // portal-facing condition must be declared in `fields[].options`.
+        for (const datarule of model.datarules ?? []) {
+            if ([3, 4, 5].includes(datarule.dataRuleType))
+                warnings.push({
+                    resource: `datarule:${model.code}.${datarule.propertyCode}`,
+                    code: "datarule-not-portal-facing",
+                    message: `字段级数据规则 type ${datarule.dataRuleType}（${datarule.dataRuleType === 4 ? "条件必填" : datarule.dataRuleType === 5 ? "条件只读" : "文本拼接"}）不驱动门户表单控件：平台把它存成 bizdatarule、只镜像进控件 historyOpt，而运行时门户读控件 options（真机复核：规则已存但发布控件无该字段、门户不拦）。要让门户生效，把条件写到字段的 options 里（fields[].options.requiredFormula / readonlyCondition / shortTextStitch）——这条路径已真机验证可穿透到发布控件；datarule 只留给服务端字段级引擎（校验/计算）。`,
+                });
+            // Dual-write advisory (dogfood R1): when the SAME field already declares
+            // the portal-facing condition in `fields[].options`, the datarule row is
+            // redundant. Surface it rather than silently writing both.
+            const field = model.fields.find((candidate) => candidate.code === datarule.propertyCode);
+            const fieldOptions = field?.options ?? {};
+            const duplicateKey = datarule.dataRuleType === 4 ? "requiredFormula" : datarule.dataRuleType === 5 ? "readonlyCondition" : undefined;
+            if (duplicateKey !== undefined && fieldOptions[duplicateKey] !== undefined)
+                warnings.push({
+                    resource: `datarule:${model.code}.${datarule.propertyCode}`,
+                    code: "datarule-duplicates-field-options",
+                    message: `字段 ${model.code}.${datarule.propertyCode} 同时在 fields[].options.${duplicateKey} 和 datarules[]（type ${datarule.dataRuleType}）声明了同一条件——门户只读 options，datarule 那条是冗余（服务端字段级引擎用）。若要门户生效保留 options 即可；datarule 仅在需要服务端强制时才必须保留。`,
+                });
+        }
+        for (const rule of model.rules ?? []) {
+            // Preset trigger rules are platform-managed: their `name` is a platform
+            // default (数据新增/数据更新/…). `rule.save` keeps the stored name for these
+            // codes, so a declared `name` is ignored — say so rather than silently
+            // dropping it (a caller who meant to rename would otherwise be confused).
+            if (PLATFORM_TRIGGER_RULE_CODES.has(rule.code))
+                warnings.push({
+                    resource: `rule:${model.code}.${rule.code}`,
+                    code: "rule-preset-name-ignored",
+                    message: `规则 ${rule.code} 是平台预置触发规则，其名称由平台维护（如 Create=数据新增）；声明的 name "${rule.name}" 不会生效（只有自定义规则的名称与节点名可改）。要改的是节点名，请改 nodeGraph/actions 中节点的 nodeName。`,
+                });
+            let graph;
+            try {
+                graph = expectedRuleGraph(rule, model.code);
+            }
+            catch {
+                continue; // shape errors are surfaced by validate/plan already
+            }
+            // Round 16 (bench66): `filter` LOCATES the rows to update, so a same-model
+            // action whose filter uses only non-unique fields updates EVERY matching
+            // row, not just the submitted one. bench66 produced status=中额 for a
+            // 120000 order because the ladder's overlapping amount-filters each matched
+            // the one row and the last one won — and a real table would have had its
+            // other rows clobbered. Keep bulk expressible (warn, don't gate) but name
+            // both fixes: locate self with `filter: [{field:id, from:id}]`, or gate the
+            // action with `when:` (an execution-gate `dataCondition`).
+            for (const node of graph.nodes ?? []) {
+                if (String(node.nodeType ?? "") !== "UPDATE")
+                    continue;
+                const target = String(node.targetObjectCode ?? "");
+                const sameModel = target === model.code || target.startsWith(`${model.code}.`);
+                if (!sameModel)
+                    continue;
+                const leaves = [];
+                walkConditionLeaves(node.filterCondition, (leaf) => leaves.push(leaf));
+                if (leaves.length === 0)
+                    continue; // no filter = default self-identity, safe
+                if (leaves.some((leaf) => String(leaf.targetSchemaDataItem) === "id"))
+                    continue;
+                warnings.push({
+                    resource: `rule:${model.code}.${rule.code}`,
+                    code: "rule-locator-not-unique",
+                    message: `规则 ${rule.code} 的 UPDATE 节点定位条件（filterCondition）未用唯一键 id：filter 是「定位要更新哪些行」，用非唯一字段（如金额/状态）会命中并更新**多条**记录（真机 bench66：金额分级误配导致多行互相覆盖）。只更新当前这条用 filter: [{field: id, from: id}]（省略 filter 时同模型动作已默认按自身 id 定位）；「输入数据满足条件才执行该节点」是执行门，用 when: [{field: <字段>, gt: <值>}]（编译到 dataCondition），与 filter 是两码事。确属批量更新可忽略本告警。`,
+                });
+            }
+            for (const finding of validateRuleNodeGraph(graph, rule.code, model.code)) {
+                if (finding.severity === "warning")
+                    warnings.push({ resource: `rule:${model.code}.${rule.code}`, code: finding.code, message: finding.message });
+            }
+        }
+    }
+    return warnings;
+}
+/** Ticket 117 — `omc intent validate <file>`: offline, zero environment contact. */
+function cmdIntentValidate(file, transport, showIntent = false) {
+    const read = readIntentOrInvalid(file, transport);
+    if (read.kind === "exit")
+        return read.code;
+    const warnings = intentWarnings(read.intent);
+    return emitResult({ status: "ok", valid: true, errors: [], digest: intentDigest(read.intent), ...(warnings.length > 0 ? { warnings } : {}), ...(showIntent ? { intent: read.intent } : {}) }, transport);
+}
+/** Round 16b — `omc intent schema [--example <id>]`: the offline DSL discovery face. */
+function cmdIntentSchema(transport, example) {
+    if (example !== undefined) {
+        const found = intentExample(example);
+        if (!found)
+            return emitInvalid(transport, {
+                message: `intent 示例 id 不存在：${example}；可用示例：${intentExampleIds().join("、")}。用 \`omc intent schema\` 看完整 schema。`,
+            });
+        return emitResult(found, transport);
+    }
+    return emitResult(intentSchemaBlock(), transport);
+}
+/** Context-cost guard: an inline plan whose JSON exceeds this (or whose decoded baseline does) is externalized to a file (see cmdIntentPlan). A populated environment's baseline is ~53 KB; a rich greenfield intent's plan is ~20 KB — both charged on every later turn. */
+const INTENT_PLAN_INLINE_CEILING_BYTES = 16384;
+/** Ticket 118 — `omc intent plan <file> --env <env>`: read-only baseline -> compile -> immutable plan. */
+async function cmdIntentPlan(file, environment, planOut, transport) {
+    const read = readIntentOrInvalid(file, transport);
+    if (read.kind === "exit")
+        return read.code;
+    const intent = read.intent;
+    // Validate the optional plan output path BEFORE any environment contact, so a
+    // bad path is a clean invalid-input (exit 10), never a wire attempt.
+    let outPath;
+    if (planOut !== undefined) {
+        try {
+            outPath = assertSafeOutputPath(intentConfigRoot(), planOut, "plan output file");
+        }
+        catch (error) {
+            return emitInvalid(transport, { message: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    let result;
+    try {
+        const context = makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
+        const session = await context.sessions.session(environment);
+        const baseline = await readBaseline(session, intent);
+        const compiled = compileIntent(intent, baseline);
+        const plan = buildPlan({
+            environment: session.environmentName,
+            environmentFingerprint: session.environmentFingerprint(),
+            compiler: INTENT_COMPILER_VERSION,
+            baseline,
+            intent,
+            compiled,
+        });
+        const planJson = JSON.stringify(plan, null, 2) + "\n";
+        const artifact = createArtifact(artifactRoot(), planJson);
+        const warnings = intentWarnings(intent);
+        const toolCounts = new Map();
+        for (const change of compiled.changes)
+            toolCounts.set(change.tool, (toolCounts.get(change.tool) ?? 0) + 1);
+        const changeSummary = [...toolCounts.entries()].map(([tool, count]) => ({ tool, count }));
+        const changePhrase = changeSummary.map(({ tool, count }) => (count > 1 ? `${tool}×${count}` : tool)).join("、") || "无";
+        console.error(`intent plan ${plan.planHash.slice(0, 12)}：${compiled.changes.length} 项变更（${changePhrase}），${compiled.skipped.length} 项已达标跳过，风险=${compiled.riskClass}；环境=${plan.environment}`);
+        if (planOut !== undefined) {
+            // Lean route (2026-09-27): the plan is the immutable approval object and
+            // its full JSON is ~11 KB for a real requirement — inlining it charges the
+            // agent's window on every later turn. Write the byte-identical plan to a
+            // file inside the config root (so `intent apply` can read it) and return
+            // only the decision fields + the path.
+            writeFileSync(outPath, planJson, { encoding: "utf8", mode: 0o600 });
+            result = {
+                status: "ok",
+                planId: plan.planHash.slice(0, 12),
+                planHash: plan.planHash,
+                // Echo the caller's own path string: an absolute host path would be
+                // redacted by the envelope, and the caller already knows the name.
+                planFile: planOut,
+                changesCount: compiled.changes.length,
+                skippedCount: compiled.skipped.length,
+                riskClass: compiled.riskClass,
+                changeSummary,
+                planArtifactId: artifact.artifactId,
+                planArtifactSha256: artifact.sha256,
+                nextAction: `omc intent apply ${planOut}`,
+            };
+        }
+        else {
+            // Context-cost guard (round 15): a populated environment's decoded
+            // baseline makes the inline plan 50–60 KB, and a rich greenfield intent's
+            // plan is ~20 KB — either is the single largest payload any read face
+            // emits, charged on every later turn. Above the ceiling, externalize the
+            // (byte-identical) immutable plan to the config root, which `intent apply`
+            // can read, and return only decision fields + the path. Small plans stay
+            // inline (deterministic on size).
+            const baselineBytes = jsonBytes(baseline);
+            const overCeiling = planJson.length > INTENT_PLAN_INLINE_CEILING_BYTES || baselineBytes > INTENT_PLAN_INLINE_CEILING_BYTES;
+            // If the config root is not writable, fall back to the inline plan (the
+            // pre-existing behaviour) rather than turning a read-only cwd into a
+            // failure.
+            let externalized = false;
+            let planFileName = "";
+            if (overCeiling) {
+                planFileName = `intent-plan-${plan.planHash.slice(0, 12)}.json`;
+                try {
+                    writeFileSync(join(intentConfigRoot(), planFileName), planJson, { encoding: "utf8", mode: 0o600 });
+                    externalized = true;
+                }
+                catch {
+                    externalized = false;
+                }
+            }
+            if (externalized) {
+                result = {
+                    status: "ok",
+                    planId: plan.planHash.slice(0, 12),
+                    planHash: plan.planHash,
+                    planFile: planFileName,
+                    changesCount: compiled.changes.length,
+                    skippedCount: compiled.skipped.length,
+                    riskClass: compiled.riskClass,
+                    changeSummary,
+                    planArtifactId: artifact.artifactId,
+                    planArtifactSha256: artifact.sha256,
+                    planExternalized: true,
+                    ...(warnings.length > 0 ? { warnings } : {}),
+                    note: `plan ${planJson.length}B（基线 ${baselineBytes}B）超过内联上限 ${INTENT_PLAN_INLINE_CEILING_BYTES}B，未内联，已写入 ${planFileName}；直接 ${"`omc intent apply " + planFileName + "`"}`,
+                    nextAction: `omc intent apply ${planFileName}`,
+                };
+            }
+            else {
+                result = {
+                    status: "ok",
+                    planId: plan.planHash.slice(0, 12),
+                    planHash: plan.planHash,
+                    changesCount: compiled.changes.length,
+                    skippedCount: compiled.skipped.length,
+                    riskClass: compiled.riskClass,
+                    plan,
+                    planArtifactId: artifact.artifactId,
+                    planArtifactSha256: artifact.sha256,
+                    ...(warnings.length > 0 ? { warnings } : {}),
+                };
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof ToolRefusalError)
+            result = error.payload;
+        else if (error instanceof WireError)
+            result = { status: "refused", blocker: `wire-${error.kind}`, errcode: error.errcode, message: error.message };
+        else
+            result = { status: "error", message: error instanceof Error ? error.message : String(error) };
+    }
+    return emitResult(result, transport);
+}
+/**
+ * Spec 107 readback core: decode the authoritative live baseline back into
+ * intent shape and compare it to the source intent. Shared by `intent readback`
+ * (equivalent:false is a legitimate not-yet-applied state, exit 0) and, since
+ * ticket 123, by `intent apply` as the final confirmation step, where a
+ * mismatch must not be reported as plain success.
+ */
+async function verifyIntentLive(session, intent) {
+    const baseline = await readBaseline(session, intent);
+    const live = decodeBaseline(baseline, intent);
+    const report = compareWithLive(intent, live);
+    return {
+        environment: session.environmentName,
+        environmentFingerprint: session.environmentFingerprint(),
+        baselineFingerprint: baselineFingerprintOf(baseline),
+        equivalent: report.equivalent,
+        differences: report.differences,
+        ignoredOutsideIntent: report.ignoredOutsideIntent,
+        live,
+    };
+}
+/**
+ * Route the decoded `live` blob to an artifact once it exceeds the inline
+ * ceiling, keeping only the decision fields (equivalent / differences /
+ * counts). Real requirements decode to tens of KB: round 9 (sandbox 43) an
+ * `intent readback` was 62 KB × ~10 calls because it inlined the full live
+ * state, and the agent redirected each to a file to avoid the context cost.
+ * Same diet as governedRead's full ceiling (src/read.ts) and the same
+ * reachability guarantee: the blob stays fully available via the artifact.
+ */
+const INTENT_LIVE_INLINE_CEILING_BYTES = 8192;
+/**
+ * Context-cost (round 15): `ignoredOutsideIntent` lists every resource outside
+ * the intent (ownership-ignored, never a difference). A real model carries ~40
+ * system fields, so a 3-model intent reported 212 entries = ~5.7 KB of pure
+ * noise on every readback — twice per task. Inline a bounded sample plus the
+ * true count; the list is informational, so nothing decision-making is lost.
+ */
+const INTENT_IGNORED_INLINE_LIMIT = 20;
+function capIgnoredOutsideIntent(verification) {
+    const ignored = verification.ignoredOutsideIntent;
+    if (!Array.isArray(ignored) || ignored.length <= INTENT_IGNORED_INLINE_LIMIT)
+        return {};
+    return {
+        ignoredOutsideIntent: ignored.slice(0, INTENT_IGNORED_INLINE_LIMIT),
+        ignoredOutsideIntentCount: ignored.length,
+        ignoredOutsideIntentHint: `意图外资源共 ${ignored.length} 项（按所有权忽略，不是差异）；此处只内联前 ${INTENT_IGNORED_INLINE_LIMIT} 项`,
+    };
+}
+function dietIntentLive(verification, context) {
+    const capped = capIgnoredOutsideIntent(verification);
+    const live = verification.live;
+    if (live === undefined)
+        return { ...verification, ...capped };
+    const bytes = jsonBytes(live);
+    if (bytes <= INTENT_LIVE_INLINE_CEILING_BYTES)
+        return { ...verification, ...capped };
+    const { live: _omitted, ...rest } = verification;
+    const ref = writeArtifact(context, `intent-live-${sha256(JSON.stringify(live)).slice(0, 16)}.json`, live);
+    return {
+        ...rest,
+        ...capped,
+        liveOmitted: true,
+        liveBytes: bytes,
+        liveArtifactHint: `权威 live 状态 ${bytes}B 超过内联上限 ${INTENT_LIVE_INLINE_CEILING_BYTES}B，已外置；上面的 equivalent/differences 已是决策所需，需要原生状态用 \`omc artifact get <detailArtifactId>\`（可 --jq <path>）定向取回`,
+        detailFile: ref.detailFile,
+        detailSha256: ref.detailSha256,
+    };
+}
+/**
+ * Ticket 120 — `omc intent readback <file> --env <env>`: decode the live
+ * baseline back into intent shape and verify equivalence. equivalent:false
+ * stays exit 0 — it is a legitimate not-yet-applied state the agent decides
+ * on (re-plan is the repair path).
+ */
+async function cmdIntentReadback(file, environment, transport) {
+    const read = readIntentOrInvalid(file, transport);
+    if (read.kind === "exit")
+        return read.code;
+    const intent = read.intent;
+    let result;
+    try {
+        const context = makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
+        const session = await context.sessions.session(environment);
+        const verification = dietIntentLive(await verifyIntentLive(session, intent), context);
+        const equivalent = verification.equivalent === true;
+        const ignoredCount = Number(verification.ignoredOutsideIntentCount ?? verification.ignoredOutsideIntent?.length ?? 0);
+        console.error(`intent readback：${equivalent ? "等价 ✓" : `${verification.differences.length} 项差异`}${ignoredCount > 0 ? `（意图外资源 ${ignoredCount} 项按所有权忽略）` : ""}`);
+        result = { status: "ok", ...verification };
+    }
+    catch (error) {
+        if (error instanceof ToolRefusalError)
+            result = error.payload;
+        else if (error instanceof WireError)
+            result = { status: "refused", blocker: `wire-${error.kind}`, errcode: error.errcode, message: error.message };
+        else
+            result = { status: "error", message: error instanceof Error ? error.message : String(error) };
+    }
+    return emitResult(result, transport);
+}
+/**
+ * Ticket 119 — `omc intent apply <plan-file>`: plan integrity + baseline
+ * drift gates, then serial execution through the EXISTING apply_changes
+ * machinery (one master approval, per-step readback, first-failure stop).
+ * No write logic is forked here — the compiled changes drive the same
+ * governed pipeline `omc call` uses.
+ */
+async function cmdIntentApply(planPath, options, transport) {
+    const emit = (result) => emitResult(result, transport);
+    const invalid = (blocker, message, code = "invalid-input") => emitInvalid(transport, { message, blocker, code });
+    let planText;
+    try {
+        planText = readIntentFile(intentConfigRoot(), planPath);
+    }
+    catch (fileError) {
+        // The plan for a large intent is externalized: `intent plan` returns
+        // `planFile` AND an artifactId. Callers read the id in the result and try
+        // `intent apply <artifactId>`, which used to fail with a bare "intent file
+        // does not exist" (bench40). Accept the artifact id directly, and otherwise
+        // name both recovery paths.
+        try {
+            planText = readArtifact(artifactRoot(), planPath).content.toString("utf8");
+        }
+        catch {
+            const hint = planPath.endsWith(".json") || planPath.includes("/") || planPath.includes("\\")
+                ? "plan 文件不存在或不在配置根内；plan 产物里有 planFile/artifactId 两种引用，直接给 planFile 或 artifactId 均可"
+                : `plan 找不到 "${planPath}"。大 plan 会外置——用 intent plan 结果里的 planFile 路径或 artifactId（可直接 \`omc intent apply <artifactId>\`）；小 plan 内联在 result.plan，先落成 .json 再传入`;
+            return invalid(undefined, `${hint}（原错误：${fileError instanceof Error ? fileError.message : String(fileError)}）`);
+        }
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(planText);
+    }
+    catch (error) {
+        return invalid(undefined, `plan 文件不是合法 JSON：${error instanceof Error ? error.message : String(error)}`);
+    }
+    const verified = verifyPlan(parsed);
+    if (!verified.ok)
+        return invalid(verified.code, verified.reason);
+    const plan = verified.plan;
+    const planId = plan.planHash.slice(0, 12);
+    if (options.env !== undefined && options.env !== plan.environment)
+        return invalid("intent-plan-environment-mismatch", `--env ${options.env} 与 plan 环境不一致（plan 属于 ${plan.environment}；plan 是不可变审批对象，不跨环境迁移）`);
+    if (options.dryRun === true) {
+        const toolCounts = new Map();
+        for (const change of plan.changes)
+            toolCounts.set(change.tool, (toolCounts.get(change.tool) ?? 0) + 1);
+        console.error(`intent apply ${planId} --dry-run：${plan.changes.length} 项变更预览，零环境写入`);
+        return emit({
+            status: "dry-run",
+            wouldChange: plan.changes.length > 0,
+            planId,
+            changes: plan.changes,
+            skippedCount: plan.skipped.length,
+            riskClass: plan.riskClass,
+            preview: [...toolCounts.entries()].map(([tool, count]) => (count > 1 ? `${tool}×${count}` : tool)).join("、") || "无变更",
+        });
+    }
+    // The whole apply holds the same cross-process write lock `omc call`
+    // acquires per write — one writer per environment across every face.
+    const lock = await acquireWriteLock(plan.environment);
+    if (!lock.held) {
+        const conflict = {
+            status: "refused",
+            blocker: "write-lock-held",
+            environment: plan.environment,
+            owner: lock.owner,
+            recovery: lock.recovery,
+            message: lock.recovery[0],
+        };
+        console.error(`write lock conflict: ${JSON.stringify(lock.owner)}`);
+        return emit(conflict);
+    }
+    try {
+        const context = makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
+        const session = await context.sessions.session(plan.environment);
+        if (session.environmentFingerprint() !== plan.environmentFingerprint)
+            return emit({
+                status: "refused",
+                blocker: "intent-plan-environment-mismatch",
+                environment: session.environmentName,
+                message: "环境指纹与 plan 不一致——plan 不跨环境迁移；在目标环境重新 intent plan",
+            });
+        // Baseline drift gate (CONTEXT.md Configuration baseline): a fingerprint
+        // change after planning invalidates the plan and requires replanning.
+        const currentBaseline = await readBaseline(session, plan.intent);
+        if (baselineFingerprintOf(currentBaseline) !== plan.baselineFingerprint)
+            return emit({
+                status: "refused",
+                blocker: "intent-baseline-drifted",
+                environment: session.environmentName,
+                message: "plan 之后环境已变化（baseline fingerprint 不一致）——按配置基线契约，写入前必须重新 intent plan；绝不盲用过期 plan",
+            });
+        // Ticket 123 — the final confirmation: after the writes (or on an
+        // already-converged no-op) decode the authoritative live state back into
+        // intent shape and compare. A mismatch is NEVER reported as plain success
+        // (blocker intent-readback-mismatch + refusal exit); it means delivery is
+        // incomplete or drifted and the agent must re-plan, not retry blindly.
+        const confirmReadback = async (base) => {
+            if (options.verify === false)
+                return base;
+            let verification;
+            try {
+                const report = await verifyIntentLive(session, plan.intent);
+                verification = { ...dietIntentLive(report, context), status: report.equivalent === true ? "ok" : "verification-failed" };
+            }
+            catch (error) {
+                verification = { status: "error", equivalent: false, error: error instanceof Error ? error.message : String(error) };
+            }
+            if (verification.equivalent === true) {
+                console.error(`intent apply ${planId}：最终读回等价 ✓（意图 ${plan.intent.models.length} 个模型）`);
+                return { ...base, verification };
+            }
+            console.error(`intent apply ${planId}：最终读回不等价——${Array.isArray(verification.differences) ? `${verification.differences.length} 项差异` : String(verification.error ?? "读回失败")}；不得当作成功`);
+            return {
+                ...base,
+                status: "refused",
+                blocker: "intent-readback-mismatch",
+                verification,
+                message: "变更已执行，但最终权威读回与意图不等价：交付可能不完整或环境已漂移。按 differences 定位后重新 intent plan（不要盲重试）",
+                nextAction: "inspect verification.differences, then re-run intent plan against the live baseline",
+            };
+        };
+        if (plan.changes.length === 0) {
+            console.error(`intent apply ${planId}：零变更（环境已达标），无审批无写入`);
+            return emit(await confirmReadback({ status: "ok", planId, intentHash: plan.intentHash, applied: 0, skipped: plan.skipped, message: "环境已达标：零变更零审批" }));
+        }
+        const registry = buildToolRegistry();
+        const applyChanges = registry.find((definition) => definition.name === "apply_changes");
+        if (!applyChanges)
+            return emit({ status: "error", message: "apply_changes 工具不可用" });
+        const changes = plan.changes.map((change) => ({ tool: change.tool, args: change.args }));
+        const toolCounts = new Map();
+        for (const change of changes)
+            toolCounts.set(change.tool, (toolCounts.get(change.tool) ?? 0) + 1);
+        const summary = `intent apply ${planId}：${changes.length} 项变更（${[...toolCounts.entries()].map(([tool, count]) => (count > 1 ? `${tool}×${count}` : tool)).join("、")}）`;
+        let result;
+        try {
+            result = (await applyChanges.handler(context, parseToolInput(applyChanges, {
+                changes,
+                environment: plan.environment,
+                summary,
+                ...(options.confirmProduction === true ? { confirmProduction: true } : {}),
+            }), applyChanges));
+        }
+        catch (error) {
+            if (error instanceof ToolInputError)
+                result = error.payload;
+            else if (error instanceof ToolRefusalError)
+                result = error.payload;
+            else if (error instanceof WireError)
+                result = { status: "refused", blocker: `wire-${error.kind}`, errcode: error.errcode, message: error.message };
+            else
+                result = { status: "error", message: error instanceof Error ? error.message : String(error) };
+        }
+        if (result.blocker === "production-confirmation-required")
+            console.error(`intent apply ${planId}：目标环境是生产环境——确认这是高危操作后，用 --confirm-production 重跑 apply（一次确认覆盖全部 ${changes.length} 步）`);
+        else
+            console.error(`intent apply ${planId}：${String(result.status)}（${changes.length} 项变更）`);
+        const applied = Array.isArray(result.steps) ? result.steps.length : undefined;
+        // Context-cost (round 15): the intent ladder's per-step `performed`/`readback`
+        // is redundant with the final intent readback-equivalence (the authority), and
+        // for a complex model it is ~17 KB of the envelope (listview columns, field
+        // publishCodes, datarule rows). Emit the step IDENTITY only; the full per-step
+        // bodies stay in the package/progress artifact (result.readback.progressFile).
+        const steps = Array.isArray(result.steps)
+            ? result.steps.map((step) => ({ step: step.step, index: step.index, status: step.status }))
+            : result.steps;
+        const delivered = { ...result, steps, planId, intentHash: plan.intentHash, ...(applied !== undefined && result.status === "ok" ? { applied } : {}) };
+        // Only a genuinely delivered package earns the final readback; a partial /
+        // refused / uncertain outcome already reports its own status and must not
+        // be papered over by a second read.
+        return emit(result.status === "ok" ? await confirmReadback(delivered) : delivered);
+    }
+    finally {
+        await lock.release();
+    }
+}
+/**
+ * Ticket 122 — `omc help [topic]`: the methodology layer, reachable exactly
+ * like `git help <concept>`. The command list is the "what"; these topics are
+ * the "how".
+ */
+function cmdHelp(topic, commandNames, transport, section, sections = false) {
+    const topics = listSkills();
+    const commands = [...commandNames].sort();
+    // Several sections in one call: `--section a --section b` or `--section a,b`.
+    // Round 15: bench60-62 each spent ~18 separate `help --section` round-trips
+    // (one per heading the route listed). Fetching them together collapses those
+    // turns without changing the bytes the caller needs. A bare `--section` (no
+    // value) still means "list this topic's sections".
+    const bareSection = Array.isArray(section) ? section.includes(true) : section === true || section === "";
+    const requestedSections = Array.isArray(section)
+        ? section.filter((value) => typeof value === "string").flatMap((value) => value.split(",")).map((value) => value.trim()).filter((value) => value.length > 0)
+        : typeof section === "string" && section.trim().length > 0
+            ? section.split(",").map((value) => value.trim()).filter((value) => value.length > 0)
+            : [];
+    // `intent` (and `call`, `commands`, …) are COMMANDS, not methodology topics; a
+    // `help intent` dead-ends. Point at the real entry (round 15 dogfood).
+    const commandPointer = topic !== undefined && !topics.some((entry) => entry.name === topic)
+        ? (/^intent$/i.test(topic)
+            ? "；`intent` 是 CLI 子命令，不是方法论 topic——用 `omc intent --help` 看子命令，或 `omc help omc-start-here --section \"声明式意图\"`"
+            : commands.includes(topic)
+                ? `；\`${topic}\` 是 CLI 命令，不是方法论 topic——用 \`omc ${topic} --help\` 看用法`
+                : "")
+        : "";
+    if (topic === undefined) {
+        console.error("用法：omc help <topic>");
+        console.error("权威路线：omc help omc-start-here（随包 skills/，不是分发镜像）");
+        console.error("环境就绪：omc call discover_environment --env <env> --args '{}'");
+        console.error(`命令：${commands.join("、")}`);
+        console.error(`方法论 topic：${topics.map((entry) => entry.name).join("、")}`);
+        return emitTransportResult({
+            status: "ok",
+            usage: "omc help <topic>",
+            discovery: DISCOVERY_AUTHORITY,
+            commands,
+            topics,
+        }, transport);
+    }
+    if (topic === "commands") {
+        console.error(`命令 ${commands.length} 项`);
+        return emitTransportResult({ status: "ok", commands }, transport);
+    }
+    if (topic === "topics") {
+        console.error(`方法论 topic ${topics.length} 项`);
+        return emitTransportResult({ status: "ok", topics }, transport);
+    }
+    if (requestedSections.length > 1) {
+        const document = topic === undefined ? undefined : readSkill(topic);
+        if (!document)
+            return emitInvalid(transport, { message: `未知 topic "${topic ?? ""}"；先用 omc help topics 查看可用 topic` });
+        const found = [];
+        const missing = [];
+        const headings = readSkillSection(topic, "__not-a-real-heading__")?.headings ?? [];
+        for (const requested of requestedSections) {
+            const sliced = readSkillSection(topic, requested);
+            if (sliced?.section)
+                found.push({ section: requested, content: sliced.section });
+            else
+                missing.push(requested);
+        }
+        if (found.length === 0)
+            return emitInvalid(transport, { message: `topic ${topic} 没有 section ${missing.map((value) => `"${value}"`).join("、")}；可用：${headings.join("、")}`, blocker: "help-section-not-found" });
+        if (missing.length > 0)
+            console.error(`help: topic ${topic} 缺少 section：${missing.join("、")}（已返回其余）`);
+        return emitTransportResult({ status: "ok", topic: document.name, ...(missing.length > 0 ? { missingSections: missing } : {}), sections: found }, transport);
+    }
+    if (sections || bareSection) {
+        const document = topic === undefined ? undefined : readSkill(topic);
+        if (!document)
+            return emitInvalid(transport, { message: `未知 topic "${topic ?? ""}"；先用 omc help topics 查看可用 topic` });
+        const sliced = readSkillSection(topic, "__not-a-real-heading__");
+        return emitTransportResult({ status: "ok", topic: document.name, sections: sliced?.headings ?? [] }, transport);
+    }
+    const singleSection = typeof section === "string" ? section : requestedSections.length === 1 ? requestedSections[0] : undefined;
+    if (singleSection !== undefined) {
+        const sliced = readSkillSection(topic, singleSection);
+        if (sliced === undefined) {
+            const message = `未知 topic "${topic}"；可用 topic：${topics.map((entry) => entry.name).join("、")}（命令清单见 omc help commands）${commandPointer}`;
+            console.error(`help: ${message}`);
+            return emitInvalid(transport, { message });
+        }
+        if (!sliced.section)
+            return emitInvalid(transport, { message: `topic ${topic} 没有 section "${singleSection}"；可用：${sliced.headings.join("、")}`, blocker: "help-section-not-found" });
+        return emitTransportResult({ status: "ok", topic: sliced.document.name, section: singleSection, content: sliced.section }, transport);
+    }
+    const document = readSkill(topic);
+    if (document === undefined) {
+        const message = `未知 topic "${topic}"；可用 topic：${topics.map((entry) => entry.name).join("、")}（命令清单见 omc help commands）${commandPointer}`;
+        console.error(`help: ${message}`);
+        return emitInvalid(transport, { message });
+    }
+    console.error(`omc help ${document.name}`);
+    return emitTransportResult({ status: "ok", topic: document }, transport);
+}
+/**
+ * The text every agent should see when it lands on `omc --help`, `omc` with no
+ * args, or `omc call --help`: how to reach the methodology router, the two
+ * write gates, and the machine-readable tool discovery. Kept in one place so
+ * those three surfaces can never drift apart.
+ */
+function onboardingHelp() {
+    return [
+        "首次使用、或不确定从哪开始：omc help omc-start-here（随包权威 topic 路线）；被拒或状态异常：omc help omc-refusals。",
+        "目标→工具一步定位：omc next \"<你要做什么>\"（离线、只读，给能力/说明/首批命令；不确定会明说并回退到 omc-requirement-analysis）。",
+        "工具发现：omc commands --json（含 capability id/lane/recipes；加 --compact 只回工具行、无目录散文）· omc capabilities（能力 id/lane/aliases/tools/依赖顺序）· omc capability <id> --executable（单能力完整执行包）。",
+        "单工具/契约：omc describe <tool>（schema+recipe+能力路由）· omc contract <lane>（wire 契约+能力路由）；环境就绪：omc call discover_environment --env <env> --args '{}'。",
+        "写入两道门：对话层草稿确认（omc help omc-config-draft-review）+ 环境 writable 开关；生产环境每笔写需在 args 里带 confirmProduction:true。",
+    ].join("\n");
+}
+async function main() {
+    let commandExitCode = 0;
+    beginUsage(argv);
+    const command = new Command();
+    try {
+        configureOutput(argv);
+    }
+    catch (error) {
+        // A malformed global output flag is invalid input, not an internal error.
+        writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message: error instanceof Error ? error.message : String(error), retryable: false }));
+        return CLI_EXIT_CODES.invalidInput;
+    }
+    command.exitOverride();
+    command.configureOutput({ writeOut: (text) => process.stderr.write(text), writeErr: (text) => process.stderr.write(text) });
+    command.name("omc").showHelpAfterError().showSuggestionAfterError(true);
+    command.addHelpText("after", `\n${onboardingHelp()}\n`);
+    // No command at all: guide the agent (help text + onboarding), exit 0. This
+    // is a benign "show me the surface" invocation, not a failure.
+    if (argv[2] === undefined) {
+        command.outputHelp();
+        return CLI_EXIT_CODES.ok;
+    }
+    command.command("help [topic]").option("--section [heading]", "按标题取该节内容；可重复或用逗号一次取多节：--section a --section b / --section a,b（不带值则列出该 topic 的节标题）", (value, previous) => [...previous, value], []).option("--sections").option("--max-output-bytes <bytes>").action(async (topic, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdHelp(topic, command.commands.map((entry) => entry.name()), transport, options.section, options.sections === true)); });
+    command.command("setup").option("--list").option("--edit <environment>").option("--remove <environment>").action(async (options) => {
+        commandExitCode = await cmdSetup(new ConfigStore(defaultPaths()), [...(options.list ? ["--list"] : []), ...(options.edit ? ["--edit", options.edit] : []), ...(options.remove ? ["--remove", options.remove] : [])]);
+    });
+    command.command("doctor").option("--environment <environment>").option("--env <environment>").action(async (options) => { commandExitCode = await cmdDoctor(new ConfigStore(defaultPaths()), options.environment ?? options.env); });
+    command.command("call <tool>").option("--env <environment>").option("--environment <environment>").option("--args <json>").option("--args-file <path>").option("--max-output-bytes <bytes>").option("--request-id <requestId>").option("--timeout-ms <milliseconds>").option("--wait <milliseconds>").option("--dry-run").addHelpText("after", `\n${onboardingHelp()}\n`).action(async (tool, options) => {
+        const rest = [tool, ...(options.env ? ["--env", options.env] : []), ...(options.environment ? ["--environment", options.environment] : []), ...(options.args !== undefined ? ["--args", options.args] : []), ...(options.argsFile !== undefined ? ["--args-file", options.argsFile] : []), ...(options.maxOutputBytes !== undefined ? ["--max-output-bytes", options.maxOutputBytes] : []), ...(options.requestId ? ["--request-id", options.requestId] : []), ...(options.timeoutMs ? ["--timeout-ms", options.timeoutMs] : []), ...(options.wait !== undefined ? ["--wait", options.wait] : []), ...(options.dryRun ? ["--dry-run"] : [])];
+        commandExitCode = await cmdCall(new ConfigStore(defaultPaths()), rest);
+    });
+    command.command("artifact").command("get <id>").option("--jq <path>").option("--path-only").option("--summary").option("--keys [a,b]").option("--max-output-bytes <bytes>").action(async (id, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdArtifactGet(id, transport, { ...(options.jq ? { jq: options.jq } : {}), pathOnly: options.pathOnly === true, summary: options.summary === true || options.keys === true, ...(typeof options.keys === "string" ? { keys: options.keys } : {}) }));
+    });
+    command.command("bench").option("--live-sample").option("--env <environment>").action(async (options) => { commandExitCode = await cmdBench([...(options.liveSample ? ["--live-sample"] : []), ...(options.env ? ["--env", options.env] : [])]); });
+    command.command("commands").option("--json").option("--compact").option("--filter <keyword>").option("--lane <id>").option("--max-output-bytes <bytes>").action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("commands", transport, undefined, { json: options.json === true, compact: options.compact === true, ...(options.filter ? { filter: options.filter } : {}), ...(options.lane ? { lane: options.lane } : {}) })); });
+    command.command("describe <tool>").option("--full").option("--schema-only").option("--param <name>").option("--example [id]").option("--max-output-bytes <bytes>").action(async (tool, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("describe", transport, tool, { full: options.full === true, schemaOnly: options.schemaOnly === true, ...(options.param ? { param: options.param } : {}), ...(options.example ? { example: options.example } : {}) }));
+    });
+    command.command("contract <lane>").option("--full").option("--tool <name>").option("--max-output-bytes <bytes>").action(async (lane, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("contract", transport, lane, { full: options.full === true, ...(options.tool ? { tool: options.tool } : {}) })); });
+    command.command("capabilities").option("--max-output-bytes <bytes>").action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdCapabilities(transport)); });
+    // `--env` is accepted but ignored: `next` is a zero-environment-contact route
+    // solver, and a caller who reflexively passes `--env` should not be refused
+    // (round 15 dogfood: `next "<goal>" --env local` → unknown option, one round).
+    command.command("next <goal>").option("--env <environment>").option("--max-output-bytes <bytes>").action(async (goal, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdNext(goal, transport));
+    });
+    command.command("usage").option("--max-output-bytes <bytes>").action(async (options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdUsage(transport));
+    });
+    command.command("capability <id>").option("--executable").option("--max-output-bytes <bytes>").action(async (id, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdCapability(id, transport, options.executable === true));
+    });
+    const intentCommand = command.command("intent");
+    intentCommand.command("schema").option("--example <id>").action((options) => { commandExitCode = cmdIntentSchema({ request, maxOutputBytes: CLI_DEFAULT_OUTPUT_BYTES }, typeof options.example === "string" ? options.example : undefined); });
+    intentCommand.command("validate <file>").option("--show-intent").action((file, options) => { commandExitCode = cmdIntentValidate(file, { request, maxOutputBytes: CLI_DEFAULT_OUTPUT_BYTES }, options.showIntent === true); });
+    intentCommand.command("plan <file>").option("--env <environment>").option("--plan-out <file>").option("--max-output-bytes <bytes>").action(async (file, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdIntentPlan(file, options.env, options.planOut, transport));
+    });
+    intentCommand.command("apply <file>").option("--env <environment>").option("--dry-run").option("--no-verify").option("--confirm-production").option("--max-output-bytes <bytes>").action(async (file, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdIntentApply(file, { env: options.env, dryRun: options.dryRun === true, verify: options.verify !== false, confirmProduction: options.confirmProduction === true }, transport));
+    });
+    intentCommand.command("readback <file>").option("--env <environment>").option("--max-output-bytes <bytes>").action(async (file, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdIntentReadback(file, options.env, transport));
+    });
+    await command.parseAsync(stripOutputFlags(argv));
+    return commandExitCode;
+}
+const request = requestId();
+main().then((code) => {
+    if (argv[2] === "call" || argv[2] === "artifact" || argv[2] === "commands" || argv[2] === "describe" || argv[2] === "contract" || argv[2] === "capabilities" || argv[2] === "capability" || argv[2] === "next" || argv[2] === "usage" || argv[2] === "intent" || argv[2] === "help") {
+        completeUsage(code);
+        exit(code);
+        return;
+    }
+    writeEnvelope(envelope(code === 0 ? "ok" : "error", {}, request, code === 0 ? null : { code: "internal", message: "command failed", retryable: false }));
+    completeUsage(code);
+    exit(code);
+}, (error) => {
+    // commander prints `--help` / `-h` usage to stderr and signals success with
+    // this code; it is not an error and must not grow a spurious error envelope.
+    if (error instanceof CommanderError && error.code === "commander.helpDisplayed") {
+        completeUsage(0);
+        exit(0);
+        return;
+    }
+    const commander = error instanceof CommanderError;
+    // A bare tool name (`omc discover_environment …`) is the most common cold-start
+    // mistake: agents drop the `call` verb. Point them at the right invocation
+    // instead of a bare "unknown command".
+    let message = error instanceof Error ? error.message : String(error);
+    if (commander && error.code === "commander.unknownCommand") {
+        const quoted = /unknown command '([^']+)'/.exec(message)?.[1];
+        if (quoted) {
+            let isTool = false;
+            try {
+                isTool = buildToolRegistry().some((tool) => tool.name === quoted);
+            }
+            catch {
+                isTool = false;
+            }
+            if (isTool)
+                message = `未知顶层命令 "${quoted}"——工具要用 omc call ${quoted} --env <env> --args '<json>'（顶层命令见 omc help commands）；环境名以 doctor 的「环境=」或 .omc-env 为准`;
+        }
+    }
+    const parsed = errorEnvelope(new Error(message), commander ? "invalid-input" : "internal", commander ? CLI_EXIT_CODES.invalidInput : CLI_EXIT_CODES.internal, request);
+    writeEnvelope(parsed.envelope);
+    completeUsage(parsed.exitCode);
+    exit(parsed.exitCode);
+});
+//# sourceMappingURL=cli.js.map