@stalfh233/omc-cli 0.5.2 → 0.5.4

package/dist/cli-output.js

@@ -44,6 +44,12 @@ export function stripOutputFlags(argv) {
         const token = normalized[index];
         if (token === "--quiet" || token === "--verbose")
             continue;
+        // `--utf8` is consumed at module load (cli.ts sets OMC_ASCII_STDOUT=0 from
+        // argv BEFORE any output is produced), so it must be stripped here too or
+        // commander rejects it as `unknown option` (r-finding 2026-10-30: the
+        // banner and README both taught `--utf8` while every invocation failed).
+        if (token === "--utf8")
+            continue;
         if (token === "--out") {
             index += 1;
             continue;

package/dist/cli.js

@@ -661,7 +661,7 @@ async function cmdArtifactGet(id, transport, options = {}) {
             if (options.jq !== undefined) {
                 const projected = projectArtifactPath(artifact.content.toString("utf8") === "" ? undefined : content, options.jq);
                 return emitTransportResult(projected.missed
-                    ? { status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, projection: { path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available }, fetch: artifactFetchHint(id) }
+                    ? { status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, unanswered: true, projection: { path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, hint: "路径未命中（这一层没有该段）。可用写法：点式 a.b、下标 a[0]、数组映射 items[].fields.x、按键选择 rules[code=Create]。available 是该层真实存在的键。" }, fetch: artifactFetchHint(id) }
                     : { status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, projection: { path: options.jq, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}) } }, transport);
             }
             return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, fetch: artifactFetchHint(id) }, transport);
@@ -685,15 +685,15 @@ async function cmdArtifactGet(id, transport, options = {}) {
                 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 };
+            const result = { status: "ok", artifactId: id, sha256: artifact.sha256, keys: wanted, ...(missing.length > 0 ? { missingKeys: missing, availableKeys: record ? Object.keys(record) : [], unanswered: true, hint: `这些键不在产物顶层：${missing.join("、")}。availableKeys 是真实顶层键；嵌套值用 --jq a.b 或 --extract a.b` } : {}), 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({ status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, projection: options.keys, ...(missing.length > 0 ? { missingKeys: missing, availableKeys: record ? Object.keys(record) : [], unanswered: true } : {}), fetch: artifactFetchHint(id) }, transport);
             return emitTransportResult(result, transport);
         }
         if (options.jq !== undefined) {
             const projected = projectArtifactPath(artifact.content.toString("utf8") === "" ? undefined : content, options.jq);
             return emitTransportResult(projected.missed
-                ? { status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, hint: `路径未命中段 "${projected.at}"——available 是该层可用的键/范围；方括号下标（a[0]）与点式（a.0）等价；[] 映射数组（items[].fields.x）` }
+                ? { status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, unanswered: true, hint: `路径未命中段 "${projected.at}"——available 是该层可用的键/范围；方括号下标（a[0]）与点式（a.0）等价；[] 映射数组（items[].fields.x）；按键选择 rules[code=Create]` }
                 : { status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}) }, transport);
         }
         // r6-onboarding 2026-10-21: 47 artifact fetches, 0 used a projection; the 10
@@ -1831,15 +1831,21 @@ async function main() {
     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("apply <file>").option("--env <environment>").option("--dry-run").option("--no-verify").option("--confirm-production").option("--wait <milliseconds>", "写锁冲突时的有界排队毫秒数（同 `omc call --wait`，默认 0=立刻拒绝）").option("--max-output-bytes <bytes>").action(async (file, options) => {
+        const waitRaw = options.wait === undefined ? 0 : Number(options.wait);
+        if (!Number.isSafeInteger(waitRaw) || waitRaw < 0 || waitRaw > 600_000) {
+            console.error("--wait must be an integer number of milliseconds from 0 to 600000");
+            commandExitCode = CLI_EXIT_CODES.invalidInput;
+            return;
+        }
+        commandExitCode = await withTransport(options, request, (transport) => cmdIntentApply(file, { env: options.env, dryRun: options.dryRun === true, verify: options.verify !== false, confirmProduction: options.confirmProduction === true, waitMs: waitRaw }, 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));
     });
     // ADR-0008: local derived rule-graph index — CLI management face, not a call
     // tool (so it stays out of `commands --json`/coverage by construction).
-    const graphCommand = command.command("graph").description("本地派生规则图索引（ADR-0008）：pull 全量重建（有界并发）/ references 离线引用 / impact 影响面 / search 规则全文 / status 完整性与新鲜度。候选定位器——不进 baseline/plan/写门禁");
+    const graphCommand = command.command("graph").description("本地派生规则图索引（ADR-0008）：pull 全量重建（有界并发）/ references 离线引用 / impact 影响面 / search 规则 code+name 检索（非规则体）/ status 完整性与新鲜度。候选定位器——不进 baseline/plan/写门禁");
     graphCommand.command("pull").option("--env <environment>").option("--environment <environment>").option("--concurrency <n>", "并发 wire 读数（1–32，默认 16）：拉取已流水线化，墙钟 ≈ max(模型面,规则面)/并发 × 延迟；过高可能触发平台限流形成缺口").option("--max-output-bytes <bytes>").addHelpText("after", "\n只读远端（model.list → 每模型 rule.list+datarule.list → 每规则 rule.get，统一任务池流水线并发）+ 本地原子重建；不写环境、不占环境写锁。新鲜度随结果回报（complete|partial），查询走 graph references / impact / search。\n").action(async (options) => {
         const parsed = options.concurrency === undefined ? undefined : Number.parseInt(String(options.concurrency), 10);
         commandExitCode = await withTransport(options, request, (transport) => cmdGraphPull(options.environment ?? options.env, parsed, transport));
@@ -1850,12 +1856,24 @@ async function main() {
     graphCommand.command("impact <kind> <code>").option("--max-output-bytes <bytes>").addHelpText("after", "\n影响面（离线）：跳1=引用该编码的规则（同 references），跳2=这些规则还读写哪些 service/model/field——改前看爆炸半径。截断上限 50 规则×每类 20 码。\n").action(async (kind, code, options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdGraphImpact(kind, code, transport));
     });
-    graphCommand.command("search <term...>").option("--max-output-bytes <bytes>").addHelpText("after", "\n规则全文检索（code+name，FTS5，末词前缀匹配）：找到\"关于 X 的规则\"拿 code，再走 references/impact。中文需给全词或词首（如 报名*）。\n").action(async (term, options) => {
+    graphCommand.command("search <term...>").option("--max-output-bytes <bytes>").addHelpText("after", "\n检索规则的 code+name（FTS5，末词前缀匹配；**不含规则体/配置内容**）。找到\"关于 X 的规则\"拿 code，再走 references/impact。中文必须是全词或词首通配（如 报名* / 增加预算*）——子串不命中：FTS5 把「增加预算」当一个 token，搜「预算」为 0。\n").action(async (term, options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdGraphSearch(term.join(" "), transport));
     });
     graphCommand.command("status").option("--max-output-bytes <bytes>").action(async (options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdGraphStatus(transport));
     });
+    // MCP stdio server (host registration: cpdocs installer's omc-graph entry;
+    // top-level verb like `codegraph serve --mcp`, not a graph subcommand).
+    // hidden like the graph lane — a transport, not a user verb. Only JSON-RPC
+    // may reach stdout from here; envelopes/banners never do.
+    command
+        .command("mcp-graph", { hidden: true })
+        .description("以 MCP stdio 服务器运行规则图检索（工具：omc_graph_explore / omc_graph_status）")
+        .option("--path <dir>", "项目根目录（定位 .omc/graph/graph.db；MCP 注册时传绝对路径，不信任宿主 cwd）")
+        .action(async (options) => {
+        const { runMcpGraphServer } = await import("./mcp-graph.js");
+        commandExitCode = await runMcpGraphServer(options.path);
+    });
     // `--jq` expressions the shell split arrive as several tokens; re-join them.
     await command.parseAsync(joinSplitFlagValues(stripOutputFlags(argv), ["--jq"]));
     return commandExitCode;

package/dist/goal-routes.js

@@ -585,7 +585,7 @@ export function goalRoute(registry, goal) {
                 readiness: DISCOVERY_AUTHORITY.readiness,
                 firstCommands: [
                     "omc describe field.update --example form-conditional-required",
-                    "omc call field.list --args '{\"schemaCode\":\"<schemaCode\",\"full\":true}'",
+                    "omc call field.list --args '{\"schemaCode\":\"<schemaCode>\",\"full\":true}'",
                 ],
                 write: true,
             },

package/dist/graph.js

@@ -4,7 +4,7 @@ import { dirname, join } from "node:path";
 import { joinConfigRoot } from "./command-transport.js";
 import { decodeJsonColumn, JSON_COLUMN_NULL_COALESCE } from "./json-column.js";
 import { ENDPOINTS } from "./endpoints.js";
-import { flattenTreeRows, resolveApplicationCode, sha256 } from "./support.js";
+import { applicationResolutionOf, flattenTreeRows, resolveApplicationScope, sha256 } from "./support.js";
 import { wireCall, wireRows } from "./wire.js";
 /**
  * `node:sqlite` must stay OUT of the CLI's startup module graph: a static
@@ -177,7 +177,8 @@ export async function pullRuleGraph(session, concurrency = DEFAULT_PULL_CONCURRE
     // returns EMPTY data on a real platform (works only against the fake face)
     // — using it here made the first live pull enumerate zero models and (pre-
     // zero-guard) wedge the scheduler.
-    const applicationCode = await resolveApplicationCode(session, undefined).catch(() => "");
+    const scope = await resolveApplicationScope(session, undefined).catch(() => undefined);
+    const applicationCode = scope?.code ?? "";
     const schemaCodes = flattenTreeRows(wireRows((await wireCall(session, { path: ENDPOINTS.applicationTree, query: { appCode: applicationCode } })).data))
         .filter((row) => row.type === "BizModel" && typeof row.code === "string" && row.code !== "")
         .map((row) => String(row.code))
@@ -368,7 +369,8 @@ export async function pullRuleGraph(session, concurrency = DEFAULT_PULL_CONCURRE
             scope: "businessrule",
             identityFingerprint: identity,
             environmentName: session.environmentName,
-            applicationCode: session.profile.applicationCode,
+            applicationCode,
+            ...(scope !== undefined ? { applicationResolution: applicationResolutionOf(scope) } : {}),
             pulledAtIso,
         },
         rules,
@@ -644,7 +646,14 @@ export function searchGraphRules(term, limit = 20) {
             rules: matches,
             index: summary,
             ...(matches.length === 0
-                ? { note: tokens.length === 0 ? "检索词为空" : "没有命中规则（code+name 全文；引用检索用 references/impact <kind> <code>）" }
+                ? {
+                    note: tokens.length === 0
+                        ? "检索词为空"
+                        // 实测摩擦（2026-10-30，zlt测试）：中文子串 0 命中后没有下一步提示，
+                        // 调用方在「换个词再试」里打转。把两个出口都写进 note：CJK 词首
+                        // 通配 + 找引用走 references/impact。
+                        : "没有命中规则。索引只覆盖规则的 code+name（不含规则体）；且只匹配**词首**——FTS5 把「增加预算」当一个词，「预算」匹配不到它。请给全词（增加预算）、词首（增加 或 增加*），或英文 code 前缀。找\"谁引用了 X\"请走 references/impact <kind> <code>。",
+                }
                 : {}),
             ...(gapped ? { gapWarning: `索引有 ${summary.gaps.count} 个扫描缺口；命中列表可能不完整` } : {}),
         };

package/dist/intent/plan-apply.js

@@ -453,7 +453,17 @@ export async function applyIntent(planPath, options, ports) {
     }
     // 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);
+    // `--wait` mirrors `omc call --wait`: bound the retry inside the CLI instead
+    // of forcing the caller to spend a round trip per conflict. Default stays 0
+    // (fail fast, structured refusal) — the opt-in is what makes it safe for
+    // non-replayable batches.
+    const waitMs = options.waitMs ?? 0;
+    const deadline = Date.now() + waitMs;
+    let lock = await acquireWriteLock(plan.environment);
+    while (!lock.held && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, Math.min(200, Math.max(0, deadline - Date.now()))));
+        lock = await acquireWriteLock(plan.environment);
+    }
     if (!lock.held) {
         const conflict = {
             status: "refused",

package/dist/lanes/businessrule.js

@@ -4,7 +4,7 @@ import { capabilityArg, environmentArg } from "../args.js";
 import { governedRead } from "../read.js";
 import { writeTool } from "../write.js";
 import { decodeJsonColumn, JSON_COLUMN_NULL_COALESCE } from "../json-column.js";
-import { flattenTreeRows, resolveApplicationCode } from "../support.js";
+import { applicationResolutionOf, applicationScopeHint, flattenTreeRows, resolveApplicationScope } from "../support.js";
 import { executeRuleSaveWrite, ruleNodeGraphArg } from "../rule-support.js";
 import { defineTool, ToolInputError, ToolRefusalError } from "../tool-types.js";
 import { resolveRuleRowId } from "../identity.js";
@@ -139,8 +139,11 @@ export function registerBusinessRuleLane(tools) {
             // Model enumeration mirrors `model.list`: the bare modelList endpoint
             // returns EMPTY rows on a real platform (live 2026-10-29: a full scan
             // "found" 0 models → false zero-hit), so walk the application tree.
+            // The implicit scope is echoed: a zero-hit scan over 1-of-N applications
+            // must not read as "nothing references this" tenant-wide.
+            const scope = args.schemaCodes === undefined ? await resolveApplicationScope(session, undefined) : undefined;
             const scoped = args.schemaCodes === undefined
-                ? flattenTreeRows(wireRows((await wireCall(session, { path: ENDPOINTS.applicationTree, query: { appCode: await resolveApplicationCode(session, undefined).catch(() => "") } })).data))
+                ? flattenTreeRows(wireRows((await wireCall(session, { path: ENDPOINTS.applicationTree, query: { appCode: scope.code } })).data))
                     .filter((row) => row.type === "BizModel" && typeof row.code === "string" && row.code !== "")
                     .map((row) => String(row.code))
                 : (Array.isArray(args.schemaCodes) ? args.schemaCodes : [args.schemaCodes]);
@@ -209,8 +212,12 @@ export function registerBusinessRuleLane(tools) {
                 code: wanted,
                 scanned: { models: scoped.length, rules: scannedRules, ...(parseFailures > 0 ? { parseFailures } : {}) },
                 matches,
+                ...(scope !== undefined ? { applicationResolution: applicationResolutionOf(scope) } : {}),
                 ...(matches.length === 0
-                    ? { note: "零命中=全平台（或指定 schemaCodes 范围内）没有规则引用它。范围：service→methodMapping.serviceCode；model→targetObjectCode/methodMapping.schemaCode；field→dataActions.targetDataItem/映射 bizCode（不含条件叶子与 datarule，第一版边界）" }
+                    ? {
+                        note: "零命中=全平台（或指定 schemaCodes 范围内）没有规则引用它。范围：service→methodMapping.serviceCode；model→targetObjectCode/methodMapping.schemaCode；field→dataActions.targetDataItem/映射 bizCode（不含条件叶子与 datarule，第一版边界）",
+                        ...(scope !== undefined ? { hint: applicationScopeHint(scope, "引用") } : {}),
+                    }
                     : {}),
             };
         }, { target: `rule.references:${args.kind}:${args.code}` }),

package/dist/lanes/dictionary-contract.js

@@ -52,7 +52,7 @@ export const DICTIONARY_LANE_CONTRACT = Object.freeze({
         "dictionary.list": Object.freeze({ scope: "dictionary list", description: "分页读取数据字典（data_dictionary/searchDictionary），返回字典元数据。" }),
         "dictionary.get": Object.freeze({ scope: "dictionary read", description: "按 id 或 code 读取数据字典及其元数据。" }),
         "dictionary.records": Object.freeze({ scope: "dictionary records read", description: "读取字典记录；支持按 id/code、启用状态和 parentId 读取，保留树形 children。" }),
-        "dictionary.save": Object.freeze({ scope: "dictionary save", description: "创建或更新数据字典及记录（data_dictionary/saveDictionary）；KEY_VALUE=0，TREE=1，写入前需审批。" }),
+        "dictionary.save": Object.freeze({ scope: "dictionary save", description: "创建或更新数据字典及记录（data_dictionary/saveDictionary）；KEY_VALUE=0，TREE=1，写入前需审批。records 是增量 upsert：传 [] 不会清空已有记录，平台也没有字典/记录删除端点——停用请用 dictionary.status，清理需维护者数据库操作。" }),
         "dictionary.status": Object.freeze({ scope: "dictionary status", description: "启用或停用字典或字典记录；停用字典时运行时不会返回选项。" }),
         "dictionary.class": Object.freeze({ scope: "dictionary classification", description: "读取、新建、删除字典分类并维护分类关联字典。" }),
         "dictionary.usage": Object.freeze({ scope: "dictionary record usage", description: "批量设置字典记录 initialUsed 使用状态；记录新增/更新仍随 dictionary.save.records。" }),

package/dist/lanes/dictionary.js

@@ -278,10 +278,39 @@ export function registerDictionaryLane(tools) {
     writeTool(tools, "dictionary.class.delete", LANE, TOOLS["dictionary.class.delete"].scope, TOOLS["dictionary.class.delete"].description, {
         ids: z.array(z.string().min(1)).min(1),
     }, async (session, args) => {
+        // The platform's deleteDictionaryClass(Batch) answers errcode 0 for ANY id —
+        // a dictionary id, a typo, anything — while deleting nothing. Writing
+        // `absent: true` unconditionally turned that into a silent false success
+        // (2026-10-30 probe: passing a dictionary id reported success and left the
+        // object in place). Verify the inputs are class ids BEFORE the write and
+        // derive absence from a post-delete read.
+        const classIds = async () => {
+            const listed = (await wireCall(session, { path: ENDPOINTS.dictionaryClasses, query: {} })).data;
+            return new Set((Array.isArray(listed) ? listed : [])
+                .map((entry) => (typeof entry.id === "string" ? entry.id : ""))
+                .filter((id) => id !== ""));
+        };
+        const before = await classIds();
+        const unmatched = args.ids.filter((id) => !before.has(id));
+        if (unmatched.length > 0) {
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "dictionary-class-absent",
+                ids: args.ids,
+                unmatched,
+                candidates: [...before].slice(0, 20),
+                message: `${unmatched.join("、")} 不是字典分类 id（删前分类列表里没有它）。平台 deleteDictionaryClass 对任意 id 都回 errcode 0 却不删任何行——传字典 id 会假成功。现有分类候选：${[...before].slice(0, 20).join("、") || "（当前没有分类）"}。另：字典本体与字典项平台无删除端点，只能 dictionary.status 停用。`,
+            });
+        }
         const path = args.ids.length === 1 ? ENDPOINTS.dictionaryClassDelete : ENDPOINTS.dictionaryClassDeleteBatch;
         const body = args.ids.length === 1 ? { id: args.ids[0] } : { ids: args.ids };
         const performed = await wireCall(session, { path, method: "POST", body });
-        return { performed: { errcode: performed.errcode, ids: args.ids }, readback: { absent: true, ids: args.ids } };
+        const after = await classIds();
+        const stillPresent = args.ids.filter((id) => after.has(id));
+        return {
+            performed: { errcode: performed.errcode, ids: args.ids },
+            readback: { absent: stillPresent.length === 0, ids: args.ids, ...(stillPresent.length > 0 ? { stillPresent } : {}) },
+        };
     }, undefined, undefined, dictionaryRollbackSpec("dictionary.class.delete"));
 }
 //# sourceMappingURL=dictionary.js.map

package/dist/lanes/model.js

@@ -9,7 +9,7 @@ import { writeSummary } from "../human-summary.js";
 import { capabilityArg, environmentArg } from "../args.js";
 import { governedRead, withoutReadbackCache } from "../read.js";
 import { parseToolInput } from "../tool-types.js";
-import { flattenTreeRows, resolveApplicationCode } from "../support.js";
+import { applicationResolutionOf, applicationScopeHint, flattenTreeRows, resolveApplicationCode, resolveApplicationScope } from "../support.js";
 import { writeTool } from "../write.js";
 import { registerPackageTool } from "../package-tool.js";
 import { defineTool, ToolInputError, ToolRefusalError } from "../tool-types.js";
@@ -196,7 +196,8 @@ export function registerModelLane(tools) {
             capability: capabilityArg,
         },
         handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
-            const applicationCode = await resolveApplicationCode(session, args.applicationCode);
+            const scope = await resolveApplicationScope(session, args.applicationCode);
+            const applicationCode = scope.code;
             const tree = flattenTreeRows(wireRows((await wireCall(session, { path: ENDPOINTS.applicationTree, query: { appCode: applicationCode } })).data));
             const all = tree
                 .filter((row) => row.type === "BizModel" && typeof row.code === "string" && row.code)
@@ -209,7 +210,19 @@ export function registerModelLane(tools) {
             // `filterApplied` disambiguates an empty result: it distinguishes "the
             // filter ran and matched nothing" from "the filter was not applied"
             // (dogfood R1: count:0 alone gave no signal).
-            return { applicationCode, count: models.length, totalBeforeFilter: all.length, filterApplied: needle !== undefined && needle !== "", ...(needle ? { filter: needle } : {}), models };
+            // `applicationResolution` says WHY this application was scanned: the
+            // implicit fallback to the tenant's first application narrows the scan to
+            // 1-of-N, so `count: 0` must never read as tenant-wide absence.
+            return {
+                applicationCode,
+                applicationResolution: applicationResolutionOf(scope),
+                count: models.length,
+                totalBeforeFilter: all.length,
+                filterApplied: needle !== undefined && needle !== "",
+                ...(needle ? { filter: needle } : {}),
+                models,
+                ...(models.length === 0 ? { hint: applicationScopeHint(scope, "模型") } : {}),
+            };
         }, { target: `model.list:${args.applicationCode ?? ""}:${args.filter ?? ""}` }),
     }));
     const siblings = tools;

package/dist/mcp-graph.js

@@ -0,0 +1,222 @@
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { GraphIndexAbsentError, graphDbPath, impactGraph, queryGraphReferences, readGraphStatus, searchGraphRules, } from "./graph.js";
+/**
+ * Stdio MCP server for the local rule-graph index (ADR-0008).
+ *
+ * Wire format is the MCP standard — newline-delimited JSON-RPC 2.0 — hand
+ * rolled on purpose: the precedent in this stack (CodeGraph) ships its own
+ * transport too, and omc-cli keeps a single-digit dependency budget. The
+ * protocol surface needed by Claude Code / Codex / WorkBuddy is small:
+ * initialize → tools/list → tools/call (+ping), everything else is -32601.
+ *
+ * Why a server at all (friction evidence, 2026-10-30 zlt测试 session):
+ *   1. CLI return shapes had to be guessed (`rules` mis-read as `matches`);
+ *      MCP tools are self-describing via input/output examples in descriptions.
+ *   2. CJK terms passed through a Windows console got mangled — a process-bound
+ *      JSON pipe is UTF-8 end to end.
+ *   3. Iterative explore→refine→explore paid a full CLI boot per question.
+ *
+ * Read-only by construction: the handlers only query the local SQLite index;
+ * `pull` deliberately stays a CLI verb (it reads the platform for ~a minute).
+ */
+const PROTOCOL_VERSION = "2024-11-05";
+const ownVersion = () => {
+    try {
+        return createRequire(import.meta.url)("../package.json").version;
+    }
+    catch {
+        return "0.0.0";
+    }
+};
+const SERVER_INFO = { name: "omc-graph", version: ownVersion() };
+const KINDS = ["field", "model", "service"];
+const MATCH_CAP = 50;
+const ERROR_CODES = { parse: -32700, invalidRequest: -32600, methodNotFound: -32601, invalidParams: -32602, internal: -32603 };
+function respond(id, result) {
+    process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: id ?? null, result })}\n`);
+}
+function respondError(id, code, message) {
+    process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: id ?? null, error: { code, message } })}\n`);
+}
+const INSTRUCTIONS_INDEXED = [
+    "规则/配置图检索（本地索引，先于逐平台扫描使用）：",
+    "- 改名/删除/重构一个 字段(field)/模型(model)/服务(service) 前，先用 omc_graph_explore 查引用与影响面；查\"谁引用了 X\"也走它。",
+    "- 索引只覆盖：业务规则（methodMapping/targetObjectCode）、数据规则（propertyCodes 与公式 {字段}）、视图（列/排序/条件）。**不含**规则条件叶子与流程绑定。",
+    "- search 语义：只匹配规则 code+name 的**词首**（中文子串不命中：搜「预算」匹配不到「增加预算」）。",
+    "答案带 freshness/pulledAtIso——索引是快照，平台侧改动后需 CLI 重建：omc graph pull --env <env>（只读远端，约 1 分钟）。",
+    "索引绑定单一环境（environmentName）；查别的环境先重新 pull。",
+].join("\n");
+const INSTRUCTIONS_NO_INDEX = [
+    "规则/配置图检索（omc-graph）：当前项目还没有本地索引（<项目>/.omc/graph/graph.db 不存在），工具暂时无法回答。",
+    "先请用户执行 CLI：omc graph pull --env <环境名>（只读远端，约 1 分钟；环境名以 omc doctor 的「环境=」或 .omc-env 为准），完成后再来调用。",
+    "不要在无索引状态下反复重试本工具。",
+].join("\n");
+const EXPLORE_TOOL = {
+    name: "omc_graph_explore",
+    description: [
+        "一次查全一个目标的引用与影响面（本地索引，毫秒级）。",
+        "输入 query=字段/模型/服务的 code（或规则检索词）；kind 可选 field|model|service，不给则三种都查。",
+        "返回 {index(freshness), references:{kind:[{schemaCode,ruleCode,nodeCode,nodeType,via}]}, impact:{kind:totals}, search:{rules}}。",
+        "改/删/重命名任何字段、模型、服务之前必查；找\"关于 X 的规则\"拿 code 也走这里。",
+        "索引不含规则条件叶子与流程绑定；freshness=partial 时命中可能不完整（答案里有 gapWarning）。",
+    ].join(" "),
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "字段/模型/服务的 code，或规则检索词（code+name 词首匹配）" },
+            kind: { type: "string", enum: [...KINDS], description: "限定一种引用种类；省略则 field/model/service 全查" },
+            env: { type: "string", description: "期望的环境名；与索引所属环境不一致时会拒绝（防跨环境误答）" },
+        },
+        required: ["query"],
+    },
+};
+const STATUS_TOOL = {
+    name: "omc_graph_status",
+    description: "索引完整性与新鲜度：environmentName、freshness(complete|partial)、模型/规则计数、pulledAtIso、gaps。回答前先看一眼，索引缺失会给出 pull 指引。",
+    inputSchema: { type: "object", properties: {} },
+};
+export function graphToolDefinitions() {
+    return [EXPLORE_TOOL, STATUS_TOOL];
+}
+function toolResult(payload, isError = false) {
+    return { content: [{ type: "text", text: JSON.stringify(payload) }], ...(isError ? { isError: true } : {}) };
+}
+function toolError(message) {
+    return toolResult({ status: "error", message }, true);
+}
+function cap(rows) {
+    return { rows: rows.slice(0, MATCH_CAP), truncated: rows.length > MATCH_CAP };
+}
+/** Shared handler core — exported so tests drive it without a stdio pair. */
+export async function executeGraphTool(name, rawArgs) {
+    const args = (rawArgs ?? {});
+    try {
+        if (name === STATUS_TOOL.name) {
+            const status = readGraphStatus();
+            return toolResult({ status: "ok", ...status });
+        }
+        if (name === EXPLORE_TOOL.name) {
+            const query = typeof args.query === "string" ? args.query.trim() : "";
+            if (!query)
+                return toolError("query 不能为空");
+            const kind = args.kind === undefined ? undefined : String(args.kind);
+            if (kind !== undefined && !KINDS.includes(kind))
+                return toolError(`kind 必须是 ${KINDS.join("|")} 之一`);
+            const status = readGraphStatus();
+            const index = status.index;
+            if (typeof args.env === "string" && args.env.trim() && args.env.trim() !== index.environmentName) {
+                return toolError(`索引属于环境「${index.environmentName}」；要查「${args.env.trim()}」请先 omc graph pull --env ${args.env.trim()} 重建索引`);
+            }
+            const kinds = kind === undefined ? [...KINDS] : [kind];
+            const references = {};
+            const impact = {};
+            for (const one of kinds) {
+                const ref = queryGraphReferences(one, query);
+                const capped = cap(ref.matches);
+                references[one] = { count: ref.matches.length, ...capped, ...(ref.gapWarning ? { gapWarning: ref.gapWarning } : {}) };
+                if (ref.matches.length > 0 || kind !== undefined) {
+                    const imp = impactGraph(one, query);
+                    impact[one] = {
+                        totals: imp.totals,
+                        rules: cap(imp.rules),
+                        datarules: cap(imp.datarules),
+                        listviews: cap(imp.listviews),
+                    };
+                }
+            }
+            const search = searchGraphRules(query);
+            return toolResult({
+                status: "ok",
+                query,
+                ...(kind !== undefined ? { kind } : {}),
+                index,
+                references,
+                impact,
+                search: { count: search.rules.length, rules: search.rules },
+                ...(search.note ? { searchNote: search.note } : {}),
+                note: "索引不含规则条件叶子与流程绑定；改这些面仍需平台侧核查",
+            });
+        }
+        return toolError(`未知工具：${name}`);
+    }
+    catch (error) {
+        if (error instanceof GraphIndexAbsentError) {
+            return toolError(`本地索引不存在（${graphDbPath()}）。先执行：omc graph pull --env <环境名>（只读远端，约 1 分钟），完成后再调用`);
+        }
+        return toolError(error instanceof Error ? error.message : String(error));
+    }
+}
+async function handleMessage(message) {
+    const id = message.id;
+    if (id === undefined || id === null)
+        return; // notification — no response
+    if (message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+        respondError(id, ERROR_CODES.invalidRequest, "invalid JSON-RPC 2.0 request");
+        return;
+    }
+    const { method } = message;
+    if (method === "initialize") {
+        const params = (message.params ?? {});
+        const requested = typeof params.protocolVersion === "string" && params.protocolVersion ? params.protocolVersion : PROTOCOL_VERSION;
+        respond(id, {
+            protocolVersion: requested,
+            capabilities: { tools: {} },
+            serverInfo: SERVER_INFO,
+            instructions: existsSync(graphDbPath()) ? INSTRUCTIONS_INDEXED : INSTRUCTIONS_NO_INDEX,
+        });
+        return;
+    }
+    if (method === "ping") {
+        respond(id, {});
+        return;
+    }
+    if (method === "tools/list") {
+        respond(id, { tools: graphToolDefinitions() });
+        return;
+    }
+    if (method === "tools/call") {
+        const params = (message.params ?? {});
+        if (typeof params.name !== "string") {
+            respondError(id, ERROR_CODES.invalidParams, "params.name must be a string");
+            return;
+        }
+        respond(id, await executeGraphTool(params.name, params.arguments));
+        return;
+    }
+    respondError(id, ERROR_CODES.methodNotFound, `method not found: ${method}`);
+}
+/**
+ * Run the stdio server. Resolves when stdin closes (the host went away).
+ * `projectRoot` (from --path) pins the index location exactly like the
+ * codegraph registration does — never trust the host's cwd.
+ */
+export async function runMcpGraphServer(projectRoot) {
+    if (projectRoot)
+        process.chdir(resolve(projectRoot));
+    const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    lines.on("line", (line) => {
+        const text = line.trim();
+        if (!text)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            respondError(null, ERROR_CODES.parse, "parse error");
+            return;
+        }
+        void handleMessage(parsed).catch((error) => {
+            respondError(idOf(parsed), ERROR_CODES.internal, error instanceof Error ? error.message : String(error));
+        });
+    });
+    await new Promise((resolve) => lines.on("close", () => resolve()));
+    return 0;
+}
+function idOf(message) {
+    return message.id ?? null;
+}
+//# sourceMappingURL=mcp-graph.js.map

package/dist/path-projection.js

@@ -96,6 +96,8 @@ function argvValues(args, name) {
     }
     return values;
 }
+/** Shared wording for every projection miss, so all three faces teach the same syntax. */
+const PATH_MISS_HINT = "路径未命中（这一层没有该段）。可用写法：点式 a.b、下标 a[0]、数组映射 items[].fields.x、按键选择 rules[code=Create]（返回第一个匹配项）。available 是该层真实存在的键。";
 /**
  * `call --extract/--extract-keys`: resolve paths inside the result's own
  * artifact (or inside the result object when the tool returned no artifact).
@@ -153,16 +155,21 @@ export function projectResultExtract(result, paths, keysOnly) {
             if (path.includes("[]")) {
                 const fanout = projectJsonPathFanout(source, path);
                 return fanout.missed
-                    ? { path, content: null, pathMiss: true, missedAt: fanout.at, available: fanout.available, missedEntries: fanout.missedEntries }
-                    : { path, content: fanout.values, mapped: fanout.values.length, ...(fanout.missedEntries > 0 ? { missedEntries: fanout.missedEntries } : {}) };
+                    ? { path, content: null, pathMiss: true, missedAt: fanout.at, available: fanout.available, missedEntries: fanout.missedEntries, hint: PATH_MISS_HINT }
+                    : { path, content: fanout.values, mapped: fanout.values.length, ...(fanout.missedEntries > 0 ? { missedEntries: fanout.missedEntries, hint: `有 ${fanout.missedEntries} 条记录在该路径下缺失，values 只含命中项` } : {}) };
             }
             const projected = projectJsonPath(source, path);
             return projected.missed
-                ? { path, content: null, pathMiss: true, missedAt: projected.at, available: projected.available }
+                ? { path, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, hint: PATH_MISS_HINT }
                 : { path, content: projected.value ?? null };
         });
         if (paths.length === 1)
             out.content = out.extract[0]?.content ?? null;
+        // A projection that missed is not an answer. `status` stays `ok` (adding a
+        // new status value would fall through classifyResult to error/exit 15 and
+        // change the exit contract), but the envelope now says so out loud.
+        if (out.extract.some((entry) => entry.pathMiss === true))
+            out.unanswered = true;
     }
     return out;
 }

package/dist/support.js

@@ -71,16 +71,52 @@ export function refusalFromCoverage(error) {
  * callers may operate across applications.
  */
 export async function resolveApplicationCode(session, requested) {
-    if (typeof requested === "string" && requested.trim())
-        return requested.trim();
-    if (session.profile.applicationCode && session.profile.applicationCode.trim())
-        return session.profile.applicationCode;
+    return (await resolveApplicationScope(session, requested)).code;
+}
+/**
+ * `resolveApplicationCode` with provenance. The fallback to the tenant's first
+ * application is legitimate (it is the documented chain) but it silently
+ * narrows a scan to 1-of-N applications — a `count: 0` from such a call reads
+ * as "does not exist" when it really means "not in this application"
+ * (2026-10-30 live: a 97-application tenant answered "no purchase model").
+ * Callers that enumerate must echo the source so a zero cannot be misread.
+ */
+export async function resolveApplicationScope(session, requested) {
+    if (typeof requested === "string" && requested.trim()) {
+        const code = requested.trim();
+        return { code, source: "explicit", requested: code };
+    }
+    if (session.profile.applicationCode && session.profile.applicationCode.trim()) {
+        const code = session.profile.applicationCode.trim();
+        return { code, source: "configured", requested: code };
+    }
     const apps = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data);
-    const first = apps.find((row) => typeof (row.appCode ?? row.code) === "string");
-    const code = first ? String(first.appCode ?? first.code) : "";
-    if (!code)
+    const codes = apps
+        .map((row) => row.appCode ?? row.code)
+        .filter((code) => typeof code === "string" && code !== "");
+    if (codes.length === 0)
         throw new WireError("business", "no application found for this environment", 302001);
-    return code;
+    return { code: codes[0], source: "first-tenant-application", requested: null, applicationCount: codes.length };
+}
+/**
+ * The echo payload for a scan-style read: `source` says why this application,
+ * `applicationCount` says how many the tenant has (fallback case only), so a
+ * zero result can never be mistaken for tenant-wide absence.
+ */
+export function applicationResolutionOf(scope) {
+    return {
+        code: scope.code,
+        source: scope.source,
+        ...(scope.requested !== null ? { requested: scope.requested } : {}),
+        ...(scope.applicationCount !== undefined ? { applicationCount: scope.applicationCount } : {}),
+    };
+}
+/** One-line nudge appended to a zero-result scan read; names the real scope of the answer. */
+export function applicationScopeHint(scope, noun) {
+    if (scope.source === "first-tenant-application" && (scope.applicationCount ?? 1) > 1) {
+        return `本次只扫描了租户首个应用 ${scope.code}（租户共 ${scope.applicationCount} 个应用）——零命中不代表其他应用没有${noun}；先 app.list 取 applicationCode 再按应用重查。`;
+    }
+    return `本次只扫描了应用 ${scope.code}（source=${scope.source}）——零命中只代表该应用没有${noun}；跨应用请先 app.list 取 applicationCode。`;
 }
 export function flattenTreeRows(rows) {
     const flat = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "CloudPivot 8.6 configuration capability CLI — governed, fail-closed, coverage-manifest bounded.",
   "type": "module",
   "bin": {
@@ -52,9 +52,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@stalfh233/omc-fake-platform": "0.5.2",
+    "@stalfh233/omc-fake-platform": "0.5.4",
     "commander": "14.0.3",
-    "omc-core": "0.5.2",
+    "omc-core": "0.5.4",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",

package/skills/omc-refusals.md

@@ -108,8 +108,10 @@ approved draft, and decide with the human. A second write may duplicate.
 3. Never blind-retry — that risks a second write.
 
 `write-lock-held` — another write holds the environment lock; `owner` and
-`recovery` are included. Wait for it to clear (it auto-recovers when the holding
-process exits), then retry. This guards concurrency, not approval.
+`recovery` are included. Retry with `--wait <ms>` (`omc call <tool> --wait 5000`,
+`omc intent apply ... --wait 5000`): the CLI does the bounded queueing in-process,
+so it costs no extra round trip. It also auto-recovers when the holding process
+exits. This guards concurrency, not approval.
 
 ## 8. Runtime / gateway errors (not tool refusals, same discipline)
 

package/skills/omc-start-here.md

@@ -31,7 +31,7 @@ be treated as a second source. Read this, then follow the topics it names.
 3. 环境名以 `omc doctor` 的「环境=」或 `.omc-env` 为准；工具不确定先用默认 `describe`/`--example`，只有单个工具缺形状才用 `--full`；`describe` 带 `exampleHint`/`recipeHint` 时优先 `--example`。
 4. 只有工具不在 `next` 命中能力内、或要看 purpose/枚举时，才补一次 `commands --json --compact --lane <lane>`。非显然形状（规则图、流程模板、表单布局、RESTFUL）才单独 `describe --example`。
 5. 键名按对象不同：模型 `schemaCode`、默认表单 `sheetCode`（可省略，默认 == 模型 code）、流程 `workflowCode`/`code`——报错会提示同义键；字段族名认不出会给「最接近的族」。
-6. **写操作串行**：同一环境不要并发写（含多个 `omc call` 并行进程——环境写锁互斥，r31 实证并行 field.create 2/3 被拒）；多个写合并为一条 `omc script` 逐行跑（进程内自动串行）；`write-lock-held` 是瞬态，等几秒重试一次即可。
+6. **写操作串行**：同一环境不要并发写（含多个 `omc call` 并行进程——环境写锁互斥，r31 实证并行 field.create 2/3 被拒）；多个写合并为一条 `omc script` 逐行跑（进程内自动串行）；`write-lock-held` 是瞬态：**优先在发起时就排队**——`omc call <tool> --wait 5000`（或 `omc intent apply ... --wait 5000`）让 CLI 内部有界重试，不必自己再花一轮。
 7. **单个对象优先高阶编排工具**：模型+字段用 `configure_model`（一次含全部字段），表单用 `configure_form`，列表用 `listview.configure`（**默认视图已存在，省略 code 即配置它，不要 `listview.create`**）。原子工具留给单点修改。
 8. 拿到 `detailArtifactId` 先 `artifact get <id> --summary` 看结构，再 `--keys/--jq` 取所需；**读面要某一列时直接 `omc call <tool> … --jq 'items[].fields.xxx'`（`[]` 映射数组，一次调用拿整列；裸 `--jq` 列键），不要再落 artifact 二次取**；`field.list`/`workflow.*` 默认面已给清单与节点摘要；`workflow.get_draft` 默认面已含 `edges`，改流程只需传 `activities`+`routes`。**注意**：`form.get --full`、`workflow.get_draft` 的 `full:true` 大结果返回的是 `{length, sha256}` 摘要桩——真身走 `artifact get <id>`，勿把桩误判为「子表/控件没配」（用户实测陷阱）。
 9. **Windows/PowerShell 乱码**：CLI 输出是 UTF-8，PowerShell 管道默认按 GBK(936) 解码会全屏乱码——根因在终端不在 CLI。消费端先 `chcp 65001` + `[Console]::OutputEncoding=[Text.Encoding]::UTF8` 再读 CLI 输出。

package/skills/omc-write-hazards.md

@@ -110,7 +110,7 @@ omc call field.publish --env local --args '{"schemaCode":"expense"}'
 
 ## 写调用纪律
 
-- **同一 `<env>` 的写调用必须串行发起**：`write-lock-held` 不只在"并行重放失败请求"时出现，也会在**并行发起两个无关写**时触发（实测：并行两条 `dictionary.save`、并行 `field.update`+`field.publish` 各失败一次）。读可并行，写不要。
+- **同一 `<env>` 的写调用必须串行发起**：`write-lock-held` 不只在"并行重放失败请求"时出现，也会在**并行发起两个无关写**时触发（实测：并行两条 `dictionary.save`、并行 `field.update`+`field.publish` 各失败一次）。读可并行，写不要。确实要并发进程时用 `--wait <ms>`（`omc call` / `omc intent apply` 都支持）让 CLI 内部排队，别把重试循环写在 shell 里。
 
 ## 审批提交的真实形状（r18b 2026-10-26 真机，1.1.25）