@cueai/omni-reader-mcp 1.5.0 → 1.5.2

package/README.md

@@ -64,7 +64,7 @@ differ from the numbers above, report the live values.
 Always use an audited exact version, never an implicit `latest`:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.5.0 setup
+npx -y @cueai/omni-reader-mcp@1.5.2 setup
 ```
 
 The interactive setup supports Hermes, Cursor, Claude Desktop, and generic stdio
@@ -72,9 +72,9 @@ configuration. Non-interactive installation uses the same argument parsing and w
 logic:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.5.0 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.5.0 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.5.0 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.2 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.2 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.2 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
 ```
 
 When an agent or script runs under a pty (stdin is still a TTY), declare non-interactive
@@ -82,9 +82,39 @@ mode explicitly with `--headless` (alias `--non-interactive`): no `--yes` is req
 stdin is never read:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.5.0 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
+npx -y @cueai/omni-reader-mcp@1.5.2 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
 ```
 
+## Windows configuration
+
+On Windows, `npx` on the command line is actually `npx.cmd` — a batch-file wrapper, not
+an executable. An MCP client that launches the server with a bare `npx` command and no
+shell therefore fails immediately with `MCP error -32000: Connection closed` before the
+server even starts. This is a launcher-shape problem, not an Omni problem: the same
+entry works unchanged on macOS and Linux.
+
+If the agent reports `Connection closed` right after connecting on Windows, use one of
+the runnable forms below. From 1.5.2 on, `setup` writes the first form automatically on
+Windows and migrates an entry that 1.5.1's `setup` wrote (the bare `npx` shape) to it
+automatically; the second is the most robust when you configure by hand.
+
+1. **`cmd` + `npx` (what `setup` writes on Windows)** — `cmd.exe` is a real executable,
+   so a client's no-shell spawn works:
+   ```json
+   { "command": "cmd", "args": ["/d", "/c", "npx", "-y", "@cueai/omni-reader-mcp@1.5.2"] }
+   ```
+2. **`node` + the package entry (most robust)** — skips `npx` entirely; the absolute
+   path must be a stable install you control:
+   ```json
+   { "command": "node", "args": ["C:\\path\\to\\node_modules\\@cueai\\omni-reader-mcp\\dist\\index.js"] }
+   ```
+   A deliberate local `npm install @cueai/omni-reader-mcp@1.5.2` gives you that stable
+   path. Do not point the entry at an `_npx` cache directory — its hash subdirectory
+   changes between installs.
+3. **Never use a session/timestamp directory** — such paths are cleaned up, and the
+   connection silently breaks at the next session. Re-run `setup` or install into a
+   stable directory instead.
+
 ## Cache and journal isolation
 
 The local parse cache and operation journal default to the user-level cache directory
@@ -221,30 +251,47 @@ satisfies the constraints.
 ## Commands
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.5.0 doctor
-npx -y @cueai/omni-reader-mcp@1.5.0 doctor --json
-npx -y @cueai/omni-reader-mcp@1.5.0 clean
-npx -y @cueai/omni-reader-mcp@1.5.0 uninstall --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.2 doctor
+npx -y @cueai/omni-reader-mcp@1.5.2 doctor --json
+npx -y @cueai/omni-reader-mcp@1.5.2 clean
+npx -y @cueai/omni-reader-mcp@1.5.2 uninstall --yes --json
 ```
 
 Running the pinned version without a command starts the stdio MCP server:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.5.0
+npx -y @cueai/omni-reader-mcp@1.5.2
 ```
 
 `doctor --json` returns package/npm/client adapter, Key present/absent, allowed-root
 safety status, endpoint compatibility, artifacts, cache mode, onboarding, and reload
 status; it never prints the Key, private source paths, or content.
 
+## Network diagnostics
+
+Bridge connects to the Omni parse API at `https://cubefile.ai.iiis.co:9443`. When a
+connection fails, run `doctor` first — its endpoint-compatibility check covers the
+API reachability from your machine. The common symptoms:
+
+| Symptom | Most likely cause | Check |
+|---|---|---|
+| `MCP error -32000: Connection closed` on Windows | launcher shape (see Windows configuration) | `doctor` package/client rows |
+| `CUBE_PROTOCOL_ERROR` or connection refused/timeout on connect | the hostname resolves to a private address on your network, or the route cannot reach the public endpoint | `nslookup cubefile.ai.iiis.co` — the public record is `122.200.68.28` |
+| Works in the browser / on another machine but not this one | a local hosts-file override hides a DNS or route problem | check `/etc/hosts` (or `C:\Windows\System32\drivers\etc\hosts`) for a `cubefile.ai.iiis.co` line; test `curl --noproxy '*' -w '%{remote_ip}\n' https://cubefile.ai.iiis.co:9443/omni/health` |
+
+If the API is reachable but a specific public URL fails to parse (`parse_timeout` /
+parse failed) while it works in your browser, that is a fetch-layer condition of the
+source on the parse API side — not a Bridge configuration problem — and it affects the
+URL the same way from every client.
+
 ## Uninstall and rollback
 
-`uninstall --yes --json` removes only a trusted 1.4.1 or 1.5.0 Bridge entry; when a
+`uninstall --yes --json` removes only a trusted 1.5.1 or 1.5.2 Bridge entry; when a
 matching trusted backup exists, it restores the original URL-only `omni-reader` entry.
 Uninstall never deletes user source files and never silently removes unexpired local
 results.
 
-To roll back from 1.5.0:
+To roll back from 1.5.2:
 
 1. stop recommending or installing that version;
 2. run `uninstall --yes --json` to restore the trusted URL-only entry;

package/dist/cli/agent-config.d.ts

@@ -41,6 +41,7 @@ export declare function agentConfigPath(target: AgentTarget, environment: AgentC
 export declare function agentBackupPath(configPath: string): string;
 export declare function displayConfigPath(configPath: string, environment: AgentConfigEnvironment): string;
 export declare function buildAgentEntry(target: AgentTarget, extraRoots: readonly string[], platform: NodeJS.Platform): Record<string, unknown>;
+export declare function expectedBridgeVersion(target: AgentTarget, value: unknown, platform: NodeJS.Platform): string | undefined;
 export declare function prepareAgentConfig(target: AgentTarget, extraRoots: readonly string[], environment: AgentConfigEnvironment): Promise<PreparedAgentConfig>;
 export declare function verifyPreparedAgentConfig(prepared: PreparedAgentConfig): Promise<void>;
 export declare function writePreparedAgentConfig(prepared: PreparedAgentConfig): Promise<void>;

package/dist/cli/agent-config.js

@@ -7,7 +7,7 @@ const PACKAGE_SPEC = `@cueai/omni-reader-mcp@${BRIDGE_RELEASE_VERSION}`;
 // The release that the current version is a trusted upgrade from: uninstall and
 // rollback recognize exactly {previous, current} and nothing else. Bump this to
 // the version we just published when BRIDGE_RELEASE_VERSION advances.
-const PREVIOUS_RELEASE_VERSION = "1.4.1";
+const PREVIOUS_RELEASE_VERSION = "1.5.1";
 const PREVIOUS_PACKAGE_SPEC = `@cueai/omni-reader-mcp@${PREVIOUS_RELEASE_VERSION}`;
 const LEGACY_PACKAGE_SPEC = "@cueai/omni-reader-mcp";
 const TRUSTED_EXACT_PACKAGE_SPECS = new Set([PREVIOUS_PACKAGE_SPEC, PACKAGE_SPEC]);
@@ -116,10 +116,14 @@ export function displayConfigPath(configPath, environment) {
     return configPath;
 }
 export function buildAgentEntry(target, extraRoots, platform) {
-    const entry = {
-        command: "npx",
-        args: ["-y", PACKAGE_SPEC],
-    };
+    // On Windows `npx` is `npx.cmd` — a batch wrapper a client cannot spawn without a
+    // shell (spawn("npx") → ENOENT, spawn("npx.cmd") → EINVAL). `cmd /d /c npx ...` is a
+    // real executable, so a no-shell spawn works (`/d` skips the AutoRun registry command,
+    // whose stdout would corrupt the MCP stdio frames); macOS/Linux keep the bare `npx`
+    // form.
+    const entry = platform === "win32"
+        ? { command: "cmd", args: ["/d", "/c", "npx", "-y", PACKAGE_SPEC] }
+        : { command: "npx", args: ["-y", PACKAGE_SPEC] };
     const env = {};
     if (target === "hermes")
         env.CUE_API_KEY = "${CUE_API_KEY}";
@@ -130,6 +134,49 @@ export function buildAgentEntry(target, extraRoots, platform) {
         entry.env = env;
     return entry;
 }
+/** The exact package spec at the invocation's spec position, given its platform shape. */
+function entryPackageSpec(entry, platform) {
+    const args = entry.args;
+    if (!Array.isArray(args))
+        return undefined;
+    if (platform !== "win32")
+        return args[1];
+    return entry.command === "npx" ? args[1] : args[4];
+}
+/**
+ * Matches the trusted invocation shape for the platform: `cmd /d /c npx -y <spec>` on
+ * Windows (runnable by a no-shell spawn; `/d` skips the AutoRun command whose stdout
+ * would corrupt MCP stdio frames), `npx -y <spec>` everywhere else. On Windows the
+ * previous release's bare-`npx` shape is additionally recognized as the migration
+ * source — 1.5.1's setup wrote it there and it can never run, but upgrade and
+ * uninstall must still identify it as a trusted entry so 1.5.2 can replace it.
+ */
+function entryInvocationMatches(entry, platform) {
+    const args = entry.args;
+    if (platform === "win32") {
+        const cmdForm = entry.command === "cmd"
+            && Array.isArray(args)
+            && args.length === 5
+            && args[0] === "/d"
+            && args[1] === "/c"
+            && args[2] === "npx"
+            && args[3] === "-y"
+            && typeof args[4] === "string"
+            && TRUSTED_EXACT_PACKAGE_SPECS.has(args[4]);
+        const previousNpxForm = entry.command === "npx"
+            && Array.isArray(args)
+            && args.length === 2
+            && args[0] === "-y"
+            && args[1] === PREVIOUS_PACKAGE_SPEC;
+        return cmdForm || previousNpxForm;
+    }
+    return entry.command === "npx"
+        && Array.isArray(args)
+        && args.length === 2
+        && args[0] === "-y"
+        && typeof args[1] === "string"
+        && TRUSTED_EXACT_PACKAGE_SPECS.has(args[1]);
+}
 function configFormat(target) {
     return target === "hermes" ? "hermes-yaml" : "json";
 }
@@ -500,7 +547,7 @@ function yamlEntry(entry, newline) {
     const args = entry.args;
     const lines = [
         "  omni-reader:",
-        "    command: npx",
+        `    command: ${entry.command}`,
         "    args:",
         ...args.map((argument) => `      - ${JSON.stringify(argument)}`),
     ];
@@ -541,16 +588,8 @@ function entryDigest(entry) {
     };
     return `sha256:${createHash("sha256").update(JSON.stringify(identity), "utf8").digest("hex")}`;
 }
-function isExpectedOmniEntry(target, value) {
-    if (!isRecord(value))
-        return false;
-    const args = value.args;
-    if (value.command !== "npx" ||
-        !Array.isArray(args) ||
-        args.length !== 2 ||
-        args[0] !== "-y" ||
-        typeof args[1] !== "string" ||
-        !TRUSTED_EXACT_PACKAGE_SPECS.has(args[1]))
+function isExpectedOmniEntry(target, value, platform) {
+    if (!isRecord(value) || !entryInvocationMatches(value, platform))
         return false;
     const keys = Object.keys(value).sort();
     if (value.env === undefined) {
@@ -586,21 +625,30 @@ function isExpectedOmniEntry(target, value) {
         && keys[1] === "command"
         && keys[2] === "env";
 }
-function expectedBridgeVersion(target, value) {
-    if (!isExpectedOmniEntry(target, value))
+export function expectedBridgeVersion(target, value, platform) {
+    if (!isExpectedOmniEntry(target, value, platform))
         return undefined;
-    const packageSpec = value.args[1];
+    const packageSpec = entryPackageSpec(value, platform);
     return packageSpec === PREVIOUS_PACKAGE_SPEC ? PREVIOUS_RELEASE_VERSION : BRIDGE_RELEASE_VERSION;
 }
-function isLegacyBridgeEntry(target, value) {
-    if (!isRecord(value) || value.command !== "npx")
+function isLegacyBridgeEntry(target, value, platform) {
+    // The legacy npx form (what every pre-1.5.2 setup wrote, incl. on Windows) plus, on
+    // Windows, the current cmd form — both are recognizable Bridge entries.
+    const legacyNpx = (entry) => {
+        const args = entry.args;
+        return entry.command === "npx"
+            && Array.isArray(args)
+            && args.length === 2
+            && args[0] === "-y"
+            && typeof args[1] === "string"
+            && (args[1] === LEGACY_PACKAGE_SPEC || TRUSTED_EXACT_PACKAGE_SPECS.has(args[1]));
+    };
+    if (!isRecord(value))
         return false;
-    const args = value.args;
-    if (!Array.isArray(args) ||
-        args.length !== 2 ||
-        args[0] !== "-y" ||
-        typeof args[1] !== "string" ||
-        (args[1] !== LEGACY_PACKAGE_SPEC && !TRUSTED_EXACT_PACKAGE_SPECS.has(args[1])))
+    const shapeOk = platform === "win32"
+        ? (legacyNpx(value) || entryInvocationMatches(value, platform))
+        : legacyNpx(value);
+    if (!shapeOk)
         return false;
     if (value.env === undefined)
         return target !== "hermes";
@@ -640,12 +688,12 @@ function hermesOmniEntry(document, displayPath) {
     }
     return entry;
 }
-function previousJsonEntry(value, displayPath) {
+function previousJsonEntry(value, displayPath, platform) {
     if (value === undefined)
         return null;
     if (isCanonicalRemoteEntry(value))
         return { format: "json", value };
-    if (isLegacyBridgeEntry("cursor", value))
+    if (isLegacyBridgeEntry("cursor", value, platform))
         return null;
     throw fileError(`The existing "omni-reader" entry in ${displayPath} is not a trusted remote or Bridge `
         + "configuration; no changes were written. Remove that entry manually, or restore a backup, "
@@ -663,7 +711,7 @@ function hermesCredentialsAreReferences(serialized) {
     }
     return true;
 }
-function previousHermesEntry(entry, displayPath) {
+function previousHermesEntry(entry, displayPath, platform) {
     if (entry === undefined)
         return null;
     const value = parseHermesEntry(entry);
@@ -675,7 +723,7 @@ function previousHermesEntry(entry, displayPath) {
         }
         return { format: "hermes-yaml", serialized: entry.serialized };
     }
-    if (isLegacyBridgeEntry("hermes", value))
+    if (isLegacyBridgeEntry("hermes", value, platform))
         return null;
     throw fileError(`The existing "omni-reader" entry in ${displayPath} is not a trusted remote or Bridge `
         + "configuration; no changes were written. Remove that entry manually, or restore a backup, "
@@ -710,7 +758,7 @@ export async function prepareAgentConfig(target, extraRoots, environment) {
         }
         const servers = existingServers ?? {};
         const existing = onlyOmniEntry(servers, displayPath);
-        const previousEntry = previousJsonEntry(existing.value, displayPath);
+        const previousEntry = previousJsonEntry(existing.value, displayPath, environment.platform);
         const afterValue = {
             ...value,
             mcpServers: {
@@ -737,7 +785,7 @@ export async function prepareAgentConfig(target, extraRoots, environment) {
     }
     const document = parseHermesDocument(loaded.serialized);
     const existing = hermesOmniEntry(document, displayPath);
-    const previousEntry = previousHermesEntry(existing, displayPath);
+    const previousEntry = previousHermesEntry(existing, displayPath, environment.platform);
     const serializedAfter = replaceHermesEntry(loaded.serialized, document, yamlEntry(entry, document.newline));
     return {
         target: "hermes",
@@ -964,7 +1012,7 @@ export async function writePreparedAgentConfig(prepared) {
         const existingBackup = await readTrustedBackup(configPath);
         let replacementBackup = backup;
         if (existingBackup !== undefined) {
-            const currentEntry = expectedConfigEntry(prepared.target, current);
+            const currentEntry = expectedConfigEntry(prepared.target, current, prepared.environment?.platform ?? "darwin");
             if (currentEntry !== undefined && existingBackup.target === prepared.target) {
                 if (existingBackup.bridge_entry_digest !== entryDigest(currentEntry)) {
                     throw fileError("A conflicting trusted Omni backup already exists; no changes were written.");
@@ -1011,21 +1059,21 @@ function jsonConfigEntry(value) {
         return undefined;
     return onlyOmniEntry(value.mcpServers, "the Agent configuration").value;
 }
-function expectedConfigEntry(target, loaded) {
+function expectedConfigEntry(target, loaded, platform) {
     if (target === "hermes") {
         const document = parseHermesDocument(loaded.serialized);
         const entry = hermesOmniEntry(document, "the Hermes configuration");
         if (entry === undefined)
             return undefined;
         const value = parseHermesEntry(entry);
-        return isExpectedOmniEntry(target, value) ? value : undefined;
+        return isExpectedOmniEntry(target, value, platform) ? value : undefined;
     }
     assertNoDuplicateJsonOmniEntries(loaded.serialized);
     const value = jsonConfigEntry(parseJsonConfig(loaded));
-    return isExpectedOmniEntry(target, value) ? value : undefined;
+    return isExpectedOmniEntry(target, value, platform) ? value : undefined;
 }
-async function configHasExpectedEntry(target, loaded) {
-    return expectedConfigEntry(target, loaded) !== undefined;
+async function configHasExpectedEntry(target, loaded, platform) {
+    return expectedConfigEntry(target, loaded, platform) !== undefined;
 }
 export async function inspectAgentConfigDetails(configPath, environment, target) {
     try {
@@ -1041,7 +1089,7 @@ export async function inspectAgentConfigDetails(configPath, environment, target)
             if (entry === undefined)
                 return { status: "not configured" };
             const value = parseHermesEntry(entry);
-            const version = expectedBridgeVersion("hermes", value);
+            const version = expectedBridgeVersion("hermes", value, environment?.platform ?? "darwin");
             if (version !== undefined)
                 return { status: "configured", version };
             return {
@@ -1055,7 +1103,7 @@ export async function inspectAgentConfigDetails(configPath, environment, target)
         const entry = onlyOmniEntry(value.mcpServers, configPath).value;
         if (entry === undefined)
             return { status: "not configured" };
-        const version = expectedBridgeVersion(resolvedTarget, entry);
+        const version = expectedBridgeVersion(resolvedTarget, entry, environment?.platform ?? "darwin");
         if (version !== undefined)
             return { status: "configured", version };
         return {
@@ -1133,7 +1181,7 @@ export async function rollbackPreparedAgentConfig(prepared) {
                 existed: true,
                 serialized: prepared.serializedBefore,
                 fingerprint: prepared.sourceFingerprint ?? "unused",
-            })
+            }, prepared.environment?.platform ?? "darwin")
             : undefined;
         if (prepared.existed) {
             await atomicReplace(prepared.configPath, prepared.serializedBefore);
@@ -1192,11 +1240,11 @@ export async function uninstallAgentConfig(target, environment) {
         return undefined;
     await validateUserConfigPath(configPath, environment);
     const initial = await readConfig(configPath);
-    if (!initial.existed || !await configHasExpectedEntry(target, initial))
+    if (!initial.existed || !await configHasExpectedEntry(target, initial, environment.platform))
         return undefined;
     return await withConfigLock(configPath, environment, async () => {
         const current = await readConfig(configPath);
-        if (!await configHasExpectedEntry(target, current)) {
+        if (!await configHasExpectedEntry(target, current, environment.platform)) {
             throw fileError("The Agent configuration changed before uninstall; no changes were written.");
         }
         const currentEntry = target === "hermes"

package/dist/constants.d.ts

@@ -6,7 +6,7 @@ export declare const CUBE_GRANT_PROTOCOL_VERSION = "omni.parse_grant.v1";
 export declare const GRANTED_STREAM_PROTOCOL_VERSION = "omni.granted_parse_stream.v1";
 export declare const DEFAULT_CUBE_BASE_URL = "https://mcp.cuecue.cn";
 export declare const DEFAULT_IIIS_GRANTED_BASE_URL = "https://cubefile.ai.iiis.co:9443/omni/granted/";
-export declare const BRIDGE_RELEASE_VERSION = "1.5.0";
+export declare const BRIDGE_RELEASE_VERSION = "1.5.2";
 export declare const REMOTE_OMNI_MCP_URL = "https://mcp.cuecue.cn/api/omni-reader/mcp/";
 export declare const FOREGROUND_BUDGET_MS = 15000;
 export declare const STATUS_LONG_POLL_MAX_MS = 20000;

package/dist/constants.js

@@ -6,7 +6,7 @@ export const CUBE_GRANT_PROTOCOL_VERSION = "omni.parse_grant.v1";
 export const GRANTED_STREAM_PROTOCOL_VERSION = "omni.granted_parse_stream.v1";
 export const DEFAULT_CUBE_BASE_URL = "https://mcp.cuecue.cn";
 export const DEFAULT_IIIS_GRANTED_BASE_URL = "https://cubefile.ai.iiis.co:9443/omni/granted/";
-export const BRIDGE_RELEASE_VERSION = "1.5.0";
+export const BRIDGE_RELEASE_VERSION = "1.5.2";
 export const REMOTE_OMNI_MCP_URL = "https://mcp.cuecue.cn/api/omni-reader/mcp/";
 export const FOREGROUND_BUDGET_MS = 15_000;
 export const STATUS_LONG_POLL_MAX_MS = 20_000;

package/dist/operation-manager.js

@@ -760,7 +760,10 @@ function remoteResultUpdate(result, expectedOperationId) {
                 operationId: result.operation_id,
                 errorCode: null,
                 parserStarted: true,
-                billed: true,
+                // Owner ruling: credits are deducted only on successful completion — the public
+                // billed flag mirrors the remote settlement facts (zero-charge completion is a
+                // settled fact, not an uncharged one). Never write true unconditionally.
+                billed: (result.billing?.credits_charged ?? 0) > 0,
                 contentReleased: true,
                 stage: "completed",
                 progressPercent: 100,
@@ -778,7 +781,11 @@ function remoteResultUpdate(result, expectedOperationId) {
                 operationId: result.operation_id,
                 errorCode: null,
                 parserStarted: true,
-                billed: true,
+                // The cleanup_pending wire carries no settlement fact (the closed v3/v4 contract
+                // exposes usage/billing only on released/delivered/delivery_expired terminals) —
+                // report false rather than inventing a charge; the journal allows a later
+                // false->true completion fact (assertStableTransition only blocks true->false).
+                billed: false,
                 contentReleased: result.result !== undefined,
                 stage: "cleanup_pending",
                 progressPercent: result.result === undefined ? 99 : 100,
@@ -869,7 +876,8 @@ function localResultValue(local) {
             operationCreated: true,
             fileUploaded: true,
             parserStarted: true,
-            billed: true,
+            // Owner ruling: an integrity failure settled nothing — never report billed:true.
+            billed: false,
             contentReleased: true,
         });
     }
@@ -996,7 +1004,8 @@ function requireBundleResult(retention) {
             operationCreated: true,
             fileUploaded: true,
             parserStarted: true,
-            billed: true,
+            // Owner ruling: an integrity failure settled nothing — never report billed:true.
+            billed: false,
             contentReleased: false,
         });
     }
@@ -1429,12 +1438,32 @@ export function createLocalParseOperationManager(options) {
                         result: processingParse(operationId, stage, latestPercent, patch.contentReleased === true),
                     };
                 }
+                const checkpointBilled = snapshot.patch?.billed === true;
                 return {
                     update: {
                         state: "FAILED",
-                        patch: failurePatch(stable),
+                        patch: {
+                            ...failurePatch(stable),
+                            // The ACK checkpoint may already have recorded a settled charge
+                            // (snapshot.patch at :1751 carries resultPatch's billed fact).
+                            // Never regress it — assertStableTransition blocks true->false —
+                            // the charge happened; this failure is about the local artifact,
+                            // not the settlement.
+                            billed: checkpointBilled || stable.billed,
+                        },
+                    },
+                    result: {
+                        status: "failed",
+                        error: {
+                            ...stable.toJSON(),
+                            // Deliberately the checkpoint fact only (not the OR): the failed
+                            // public result reports exactly what this run settled — false
+                            // when nothing was settled (owner ruling), true when the ACK
+                            // checkpoint already recorded the charge and the failure is
+                            // about local delivery, not the settlement.
+                            billed: checkpointBilled,
+                        },
                     },
-                    result: { status: "failed", error: stable.toJSON() },
                 };
             }
             finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueai/omni-reader-mcp",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Local stdio MCP bridge for direct Omni document parsing",
   "type": "module",
   "license": "UNLICENSED",