@getmarrow/mcp 3.9.96 → 3.9.98

package/README.md

@@ -136,7 +136,15 @@ v3.9.87 hardens the authenticated control-path canary against single-sample tran
 
 v3.9.86 was published with the adapter version constant still at `3.9.85`, so the strict canary identity check rejected it; it is deprecated — use `3.9.87`. SDK `3.7.62` and installer `0.1.56` are unchanged; install MCP `3.9.87`, reload the host, review hook trust, and verify before claiming the updated client is active.
 
-## What's New in v3.9.96
+## What's New in v3.9.98
+
+v3.9.98 fixes `npx @getmarrow/mcp setup` and every other `npx @getmarrow/mcp …` command. Since 3.9.57 they failed with "could not determine executable to run", because the package had two executables and none named after the package. The package now also provides an executable named `mcp`, so those commands work again. `marrow-mcp` and `marrow-mcp-canary` are unchanged, and the `npx -y --package=@getmarrow/mcp@latest marrow-mcp …` commands shown in this README keep working. If you install the package globally (`npm install -g @getmarrow/mcp`), it now also adds a command named `mcp`, which may share a name with other tools; `npx` users are unaffected. Tools, hooks and policy behavior are unchanged.
+
+### Previous release: v3.9.97
+
+v3.9.97 makes native hook control easier to live with. Free and starter gates are advisory again, so an advisory gate no longer hard-blocks work; a `block` decision still denies on every plan. In Claude Code's default, acceptEdits and auto permission modes, an enforced review now shows an owner-approval prompt instead of a denial. In plan, dontAsk and bypassPermissions modes, and for arbitration reviews, the action is still denied. Read-only commands such as `git show`, `git log` and `ls` no longer trigger false blocks, and denial messages now say plainly why an action was stopped and what to do next. The hook sends `protocol_version` when it verifies an action permit. When an action is denied, the hook makes a best-effort attempt, capped at 2.5 s, to close the decision with a denied outcome; if the backend does not confirm, the decision stays open. Hooks return faster because telemetry is delivered by a detached background process that honors opt-outs and never blocks the action (see `MARROW_HOOK_BACKGROUND_NUDGE` in Environment). Pending writes are retried more reliably: the client honors `retry_after_ms` and the optional `lease_remaining_ms`, and resumes the same write instead of starting a new one (see `MARROW_WRITE_RECONCILIATION_BUDGET_MS`). Hook lifecycle receipts are much less likely to be dropped when many hook processes write the spool at once: each event takes the spool lock fewer times, and the lock wait is a 10 s time budget with randomized polling. A receipt can still be lost if the lock is held for the full 10 s. Policy decisions, proof requirements and fail-closed behavior are unchanged, except that an enforced review now asks the owner (in the modes above) instead of denying. Update, reload the host and review hook trust before relying on the new hook.
+
+### Previous release: v3.9.96
 
 v3.9.96 fixes native pre-action hooks that denied protected actions after the runtime gate allowed them. The hook sent `source_meta` fields that Think rejects, and without a risk level the runtime answered protected actions on its low-risk fast path, whose receipt cannot back an action permit. Protected actions now request a durable gate and create their decision with accepted metadata only; unprotected actions stop at the gate without creating a decision or permit. A rejected control call now names its HTTP status and failure code without echoing service text. Policy decisions, proof requirements and fail-closed behavior are unchanged. Update, reload the host and review hook trust before relying on the new hook.
 
@@ -672,6 +680,8 @@ See the [Trust Center](https://getmarrow.ai/trust/) for implemented controls, cu
 | `MARROW_BASE_URL` | No | API base override |
 | `MARROW_AGENT_ID` | No | Bound agent identity for MCP tools |
 | `MARROW_FLEET_AGENT_ID` | No | Fleet agent identity used by passive setup |
+| `MARROW_HOOK_BACKGROUND_NUDGE` | No | Default on: PostToolUse only spools the event and starts one detached background process that delivers it, so the hook adds almost no latency. Set to `false` to keep bounded inline delivery (750 ms) inside the hook. Never runs when `MARROW_AUTO_HOOK=false` or local control is disabled |
+| `MARROW_WRITE_RECONCILIATION_BUDGET_MS` | No | Default `15000`, range 1000-60000: total time a pending think or commit may wait, resuming the same idempotency key and request hash after the server's `retry_after_ms` or `Retry-After`. When the next wait does not fit, the call returns the resumable pending receipt and never reports success |
 
 ## Documentation
 

package/dist/cli.js

@@ -18,6 +18,7 @@ const hook_contract_1 = require("./hook-contract");
 const hook_context_1 = require("./hook-context");
 const hook_session_1 = require("./hook-session");
 const hook_pre_action_1 = require("./hook-pre-action");
+const node_child_process_1 = require("node:child_process");
 const env_1 = require("./env");
 const lifecycle_spool_1 = require("./lifecycle-spool");
 const spool_command_1 = require("./spool-command");
@@ -61,6 +62,9 @@ function parseArgs() {
         if (args[i] === 'drain-spool' || args[i] === '--drain-spool') {
             result.drainSpool = true;
         }
+        if (args[i] === 'background-nudge') {
+            result.backgroundNudge = true;
+        }
         if (args[i] === 'ping' || args[i] === '--ping') {
             result.ping = true;
         }
@@ -81,6 +85,62 @@ function reportLifecycleSpool(input) {
     }
     return spool;
 }
+// PostToolUse only spools. When this invocation actually spooled an event (so it passed
+// MARROW_AUTO_HOOK, local-control and read-only gates), start one detached, unref'd
+// process that delivers with the longer background timeout. No spool scan happens here.
+function launchBackgroundLifecycleNudge() {
+    try {
+        if (!(0, hook_1.hookSpooledLifecycleEvent)() || !(0, lifecycle_spool_1.backgroundNudgeEnabled)())
+            return;
+        const identity = (0, hook_contract_2.resolveNativeHookIdentity)(process.argv[2]);
+        const apiKey = identity.environment.apiKey || '';
+        if (!apiKey)
+            return;
+        const nonce = (0, lifecycle_spool_1.claimBackgroundNudgeLock)({ apiKey, agentId: identity.agent_id });
+        if (!nonce)
+            return;
+        const child = (0, node_child_process_1.spawn)(process.execPath, [process.argv[1], 'background-nudge'], {
+            detached: true, stdio: 'ignore', windowsHide: true,
+            env: { ...process.env, MARROW_INTERNAL_NUDGE_LOCK: nonce },
+        });
+        child.on('error', () => (0, lifecycle_spool_1.releaseBackgroundNudgeLock)({ apiKey, agentId: identity.agent_id, nonce }));
+        child.unref();
+    }
+    catch { /* the event stays spooled for the next nudge */ }
+}
+async function runBackgroundNudge() {
+    const identity = (0, hook_contract_2.resolveNativeHookIdentity)(undefined);
+    const apiKey = identity.environment.apiKey || '';
+    const agentId = identity.agent_id;
+    let nonce = process.env.MARROW_INTERNAL_NUDGE_LOCK || '';
+    const release = () => { if (apiKey && nonce)
+        (0, lifecycle_spool_1.releaseBackgroundNudgeLock)({ apiKey, agentId, nonce }); };
+    // Hard lifetime cap, below the lock's stale threshold.
+    const watchdog = setTimeout(() => { release(); process.exit(0); }, lifecycle_spool_1.BACKGROUND_NUDGE_MAX_LIFETIME_MS);
+    try {
+        if (!apiKey || !nonce)
+            return;
+        const baseUrl = (0, index_1.validateBaseUrl)(identity.environment.baseUrl || 'https://api.getmarrow.ai');
+        // Deliver, then re-check once for events spooled while this process held the lock.
+        for (let round = 0; round < 3; round += 1) {
+            await (0, lifecycle_spool_1.nudgeLifecycleSpool)({ apiKey, baseUrl, agentId });
+            if (!(0, lifecycle_spool_1.hasDueLifecycleEvents)({ apiKey, agentId }))
+                break;
+        }
+        release();
+        const next = (0, lifecycle_spool_1.hasDueLifecycleEvents)({ apiKey, agentId }) ? (0, lifecycle_spool_1.claimBackgroundNudgeLock)({ apiKey, agentId }) : null;
+        if (next) {
+            nonce = next;
+            await (0, lifecycle_spool_1.nudgeLifecycleSpool)({ apiKey, baseUrl, agentId });
+        }
+    }
+    catch { /* best effort */ }
+    finally {
+        clearTimeout(watchdog);
+        release();
+        process.exit(0);
+    }
+}
 async function runPingCommand() {
     if (cliArgs.apiKey) {
         process.stderr.write('Error: ping requires MARROW_API_KEY from trusted environment or owner configuration; --key is not accepted.\n');
@@ -365,7 +425,10 @@ if (process.argv[2] === 'keys') {
 // Only start MCP server if not handling a CLI command
 if (process.argv[2] !== 'keys') {
     if (cliArgs.hook) {
-        void (0, hook_1.runHookCommand)();
+        void (0, hook_1.runHookCommand)().finally(launchBackgroundLifecycleNudge);
+    }
+    else if (cliArgs.backgroundNudge) {
+        void runBackgroundNudge();
     }
     else if (cliArgs.contextHook) {
         void (0, hook_context_1.runContextHookCommand)();