@stalfh233/omc-cli 0.5.3 → 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,8 +1831,14 @@ 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));

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,

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/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.3",
+  "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.3",
+    "@stalfh233/omc-fake-platform": "0.5.4",
     "commander": "14.0.3",
-    "omc-core": "0.5.3",
+    "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）