@getmarrow/mcp 3.9.57 → 3.9.59

package/README.md

@@ -57,7 +57,7 @@ Verify current claims through the [public evidence manifest](https://getmarrow.a
 ## Install
 
 ```bash
-npx @getmarrow/mcp setup
+npx -y --package=@getmarrow/mcp@latest marrow-mcp setup
 ```
 
 Set the key through trusted secret storage:
@@ -75,7 +75,7 @@ Then configure the MCP server:
   "mcpServers": {
     "marrow": {
       "command": "npx",
-      "args": ["-y", "@getmarrow/mcp"]
+      "args": ["-y", "--package=@getmarrow/mcp@latest", "marrow-mcp"]
     }
   }
 }
@@ -96,17 +96,39 @@ npx -y @getmarrow/install@latest activate
 npx -y @getmarrow/install@latest doctor
 
 # Manual MCP-only setup
-npx -y @getmarrow/mcp@latest setup
+npx -y --package=@getmarrow/mcp@latest marrow-mcp setup
 
 # Verify live read latency, last success, and local backlog
-npx -y @getmarrow/mcp@latest ping
+npx -y --package=@getmarrow/mcp@latest marrow-mcp ping
 ```
 
 Detection and notification are automatic. After explicit installer activation, the local controller may restore only Marrow-managed hooks/configuration. Package upgrades, owner policy, credentials, and unrelated configuration remain explicit and subject to the operator's normal change policy.
 
-## What's New in v3.9.57
+## What's New in v3.9.59
 
-v3.9.57 makes the agent control path reliable and deliberately small by default:
+v3.9.59 makes the six-tool control path reliable and honest across ordinary edge and geographic latency:
+
+- the default health deadline is 2.5 seconds instead of an unrealistically narrow 400 ms;
+- `MARROW_PING_TIMEOUT_MS` can tune the probe between 500 ms and 5 seconds;
+- authenticated control reads tolerate cold network/TLS paths while cached reads still return quickly;
+- status, ask, runtime, and handoff responses report measured current/p50/p99 latency plus owner-only queue health;
+- a first-session outage returns a clearly labeled local safety brief, and infrastructure failures are never mislabeled as policy denials;
+- timeout errors return a concrete retry delay instead of an unresolved placeholder;
+- Cloudflare edge denials are separated from key-scope or Marrow policy rejections;
+- MCP initialization carries the always-on control/proof instructions even when a client does not request the optional prompt template;
+- update, launch, setup, spool, and ping commands use the unambiguous `npx --package ... marrow-mcp` form;
+- explicit spool drains tolerate slow edge delivery without extending passive hook latency.
+
+## Previous: v3.9.58
+
+v3.9.58 makes latency evidence accurate by reusing one initialized MCP process for the complete control-path canary:
+
+- startup, initialization, and tool discovery are measured separately from authenticated tool calls;
+- hot-path steering and report latency are reported as separate p50, p95, p99, and maximum groups;
+- response IDs, malformed output, RPC failures, timeouts, and incomplete tool contracts fail closed;
+- one bounded process prevents package and process startup time from being mistaken for API latency.
+
+The compact agent control path introduced in v3.9.57 remains the default:
 
 - `marrow_status`, `marrow_ask`, and `marrow_agent_runtime` use authenticated routes with bounded retries and typed failures;
 - transient read failures return an owner-only last-known brief when available, while cached guidance can never authorize high-risk work;
@@ -126,7 +148,7 @@ v3.9.56 adds tenant-scoped coordination and evidence-only replay to the existing
 - transient failures can use an owner-only, account/key/agent-scoped last-known brief for at most one hour, clearly labeled with its age;
 - 401 and 403 responses never use cached guidance, and cached runtime guidance cannot authorize high-risk work;
 - `marrow_ask` now maps to the canonical decision brief contract instead of a separate route;
-- `npx -y @getmarrow/mcp@latest ping` reports current latency, rolling measured p50/p99, last success, and lifecycle backlog health;
+- `npx -y --package=@getmarrow/mcp@latest marrow-mcp ping` reports current latency, rolling measured p50/p99, last success, and lifecycle backlog health;
 - `marrow_coordinate` acquires/releases tenant-scoped resource leases and carries compact child proof packets without sharing transcripts;
 - `marrow_replay_compare` compares already-recorded baseline and candidate outcomes with durable proof and never executes either model;
 - both new tools preserve agent-bound key scope, reject unsafe path identifiers, and return unavailable or incomplete evidence rather than manufacturing a winner.
@@ -309,15 +331,15 @@ it does not run models, retain prompts, or infer a winner from labels.
 
 ## Passive Use
 
-`npx @getmarrow/mcp setup` installs supported prompt, tool-result, and session-stop hooks so the agent can receive before-action context, record meaningful tool outcomes, and keep unfinished closure visible without the owner repeatedly prompting it to use Marrow.
+`npx -y --package=@getmarrow/mcp@latest marrow-mcp setup` installs supported prompt, tool-result, and session-stop hooks so the agent can receive before-action context, record meaningful tool outcomes, and keep unfinished closure visible without the owner repeatedly prompting it to use Marrow.
 
 The hooks send compact classifications and lifecycle receipts. They do not need raw prompts, completions, command output, tool output, or credentials. A completed tool or session does not automatically become a successful business outcome; explicit success/failure closure is required.
 
 Transient lifecycle receipts use a bounded owner-only spool and are retried with stable event IDs. Operators can inspect and drain it without exposing event content:
 
 ```bash
-npx @getmarrow/mcp spool-status
-npx @getmarrow/mcp drain-spool
+npx -y --package=@getmarrow/mcp@latest marrow-mcp spool-status
+npx -y --package=@getmarrow/mcp@latest marrow-mcp drain-spool
 ```
 
 The output contains only state, exact pending/failed counts, oldest receipt timestamps, capacity, and an exact fix. Terminal validation/authentication failures and exhausted retries remain explicit durable failures rather than cycling indefinitely.

package/dist/cli.js

@@ -21,6 +21,7 @@ const guidance_cache_1 = require("./guidance-cache");
 const request_reliability_1 = require("./request-reliability");
 const hook_contract_1 = require("./hook-contract");
 const ping_state_1 = require("./ping-state");
+const control_path_state_1 = require("./control-path-state");
 const redact_1 = require("./redact");
 const runtime_contract_1 = require("./runtime-contract");
 // Parse CLI args
@@ -73,7 +74,7 @@ async function runPingCommand() {
     }
     const baseUrl = (0, index_1.validateBaseUrl)(resolved.baseUrl || 'https://api.getmarrow.ai');
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 400);
+    const timer = setTimeout(() => controller.abort(), (0, ping_state_1.resolvePingTimeoutMs)(process.env.MARROW_PING_TIMEOUT_MS));
     timer.unref?.();
     const started = Date.now();
     try {
@@ -127,11 +128,13 @@ async function runSpoolCommand(drain) {
         ? await (0, lifecycle_spool_1.drainLifecycleSpool)({ apiKey, baseUrl, agentId: resolved.agentId || undefined })
         : (0, lifecycle_spool_1.lifecycleSpoolStatus)({ apiKey, agentId: resolved.agentId || undefined });
     process.stdout.write(`${JSON.stringify({
-        ok: status.state !== 'attention_required',
+        ok: drain ? status.state === 'clear' : status.state !== 'attention_required',
         lifecycle_spool: status,
     }, null, 2)}\n`);
     if (status.state === 'attention_required')
         process.exitCode = 2;
+    else if (drain && status.state !== 'clear')
+        process.exitCode = 1;
 }
 // ─── Setup command: inject Marrow instructions into CLAUDE.md ───
 function runSetup() {
@@ -441,27 +444,56 @@ if (process.argv[2] !== 'keys') {
         }
         function toolFailure(toolName, failure) {
             const result = (0, request_reliability_1.structuredRequestFailure)(failure);
-            const transient = failure.retryable && !['authentication_required', 'permission_denied'].includes(failure.code);
-            const supportsStale = ['marrow_agent_runtime', 'marrow_orient', 'marrow_ask', 'marrow_runtime_status', 'marrow_status'].includes(toolName || '');
-            if (transient && supportsStale) {
+            const infrastructureFailure = !['authentication_required', 'permission_denied'].includes(failure.code);
+            const supportsStale = ['marrow_agent_runtime', 'marrow_orient', 'marrow_ask', 'marrow_handoff_status', 'marrow_runtime_status', 'marrow_status'].includes(toolName || '');
+            const spool = (0, lifecycle_spool_1.lifecycleSpoolStatus)({ apiKey: API_KEY, agentId: FLEET_AGENT_ID });
+            result.failure_kind = infrastructureFailure ? 'infrastructure' : 'authorization';
+            result.control_path = (0, control_path_state_1.controlPathStats)(toolName || 'marrow_control');
+            result.lifecycle_spool = {
+                ...spool,
+                drain_command: 'npx -y --package=@getmarrow/mcp@latest marrow-mcp drain-spool',
+            };
+            if (infrastructureFailure && supportsStale) {
                 let cached = null;
                 try {
                     cached = (0, guidance_cache_1.readGuidanceCache)({ apiKey: API_KEY, baseUrl: BASE_URL, agentId: FLEET_AGENT_ID });
                 }
                 catch { /* owner-only cache is best effort */ }
-                if (cached) {
-                    result.stale_brief = cached.context;
-                    result.stale_ms = cached.stale_ms;
-                }
-                result.disposition = 'review_required';
-                result.allow = false;
+                result.stale_brief = cached?.context || [
+                    '## Marrow control-path outage brief',
+                    '- This is an infrastructure failure; Marrow returned no policy decision and did not deny the action.',
+                    '- Preserve local evidence and continue only low-risk, reversible work under the owner\'s existing safeguards.',
+                    '- Do not perform high-risk work until a fresh Marrow runtime gate returns allow, warn, review_required, or block.',
+                ].join('\n');
+                result.stale_source = cached ? 'last_known_guidance' : 'local_outage_safety';
+                result.stale_ms = cached?.stale_ms ?? null;
+                result.authorization_state = 'unavailable';
+                result.gate_obtained = false;
                 result.stale_can_authorize_high_risk = false;
+                const retryAfterMs = failure.retryAfterMs;
                 result.exact_next_action = cached
                     ? 'Use this last-known brief for low-risk context only. Obtain a fresh Marrow runtime gate before high-risk work.'
-                    : 'Retry once after retry_after_ms. Do not perform high-risk work without a fresh Marrow runtime gate.';
+                    : retryAfterMs != null
+                        ? `Wait ${retryAfterMs} ms, then retry once. Do not perform high-risk work without a fresh Marrow runtime gate.`
+                        : failure.exactFix;
             }
             return result;
         }
+        function clientOperationalPayload(toolName, value) {
+            const payload = value && typeof value === 'object' && !Array.isArray(value)
+                ? value
+                : { data: value };
+            const spool = (0, lifecycle_spool_1.lifecycleSpoolStatus)({ apiKey: API_KEY, agentId: FLEET_AGENT_ID });
+            return {
+                ...payload,
+                client_update: payload.client_update || (0, request_reliability_1.localClientUpdate)(),
+                control_path: (0, control_path_state_1.controlPathStats)(toolName),
+                lifecycle_spool: {
+                    ...spool,
+                    drain_command: 'npx -y --package=@getmarrow/mcp@latest marrow-mcp drain-spool',
+                },
+            };
+        }
         // [FIX #9] Runtime validation helper for required string params
         function requireString(args, name) {
             const val = args[name];
@@ -489,16 +521,24 @@ if (process.argv[2] !== 'keys') {
             }
         }
         async function withControlDeadline(operation, options = {}) {
+            const toolName = options.toolName || 'marrow_control';
             const hasCache = options.cacheAware !== false && Boolean(cachedGuidance());
-            const configuredCanaryMs = Number(process.env.MARROW_REQUEST_TIMEOUT_MS);
-            const timeoutMs = process.env.MARROW_CONTROL_PATH_CANARY === '1' && Number.isFinite(configuredCanaryMs)
-                ? Math.min(5_000, Math.max(500, Math.floor(configuredCanaryMs)))
-                : options.highRisk ? 2_000 : hasCache ? 400 : 1_200;
+            const configuredTimeoutMs = Number(process.env.MARROW_REQUEST_TIMEOUT_MS);
+            const timeoutMs = Number.isFinite(configuredTimeoutMs)
+                ? Math.min(10_000, Math.max(150, Math.floor(configuredTimeoutMs)))
+                : options.highRisk ? 4_500 : hasCache ? 500 : 4_000;
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), timeoutMs);
             timer.unref?.();
+            const startedAt = Date.now();
             try {
-                return await operation(controller.signal);
+                const result = await operation(controller.signal);
+                (0, control_path_state_1.recordControlPathSample)(toolName, Date.now() - startedAt, true);
+                return result;
+            }
+            catch (error) {
+                (0, control_path_state_1.recordControlPathSample)(toolName, Date.now() - startedAt, false);
+                throw error;
             }
             finally {
                 clearTimeout(timer);
@@ -1631,6 +1671,9 @@ if (process.argv[2] !== 'keys') {
                         protocolVersion: '2024-11-05',
                         capabilities: { tools: {}, prompts: {} },
                         serverInfo: { name: 'marrow', version: hook_contract_1.MCP_ADAPTER_VERSION },
+                        ...(AUTO_ENROLL ? {
+                            instructions: 'Use marrow_agent_runtime before consequential actions, obey fresh allow/warn/review_required/block results, use marrow_ask for relevant prior lessons, and close meaningful outcomes with marrow_commit. Infrastructure failures are not policy denials; continue only low-risk reversible work from the returned outage-safe brief, and require a fresh gate for high-risk work.',
+                        } : {}),
                     });
                     // Auto-enroll: emit enrollment notification on connection
                     if (AUTO_ENROLL) {
@@ -1731,7 +1774,7 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                         orientCallCount++;
                         const wantAutoWarn = args.autoWarn ?? true;
                         const taskType = args.taskType;
-                        const result = await withControlDeadline((signal) => (0, index_1.marrowOrient)(API_KEY, BASE_URL, { taskType, autoWarn: wantAutoWarn }, SESSION_ID, FLEET_AGENT_ID, signal), { highRisk: isHighRiskAction(`Orient before ${taskType || 'general'} work`, taskType) });
+                        const result = await withControlDeadline((signal) => (0, index_1.marrowOrient)(API_KEY, BASE_URL, { taskType, autoWarn: wantAutoWarn }, SESSION_ID, FLEET_AGENT_ID, signal), { highRisk: isHighRiskAction(`Orient before ${taskType || 'general'} work`, taskType), toolName: 'marrow_orient' });
                         if (AUTO_ENROLL && orientCallCount === 1) {
                             const enrollmentText = `\n\n**Marrow control and proof active**\n\n` +
                                 `Marrow applies relevant policy and prior lessons before consequential actions, then records evidence and the real outcome afterward.\n\n` +
@@ -1905,7 +1948,7 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                                 session_id: SESSION_ID,
                                 proof: suppliedProof,
                                 context: { source: 'mcp_auto_risk_upgrade' },
-                            }, SESSION_ID, FLEET_AGENT_ID, signal), { highRisk: true });
+                            }, SESSION_ID, FLEET_AGENT_ID, signal), { highRisk: true, toolName: 'marrow_auto.runtime' });
                             storeRuntimeGuidance(runtimeGate);
                         }
                         const proofCanClose = !highRisk || (0, runtime_contract_1.highRiskRuntimeCanClose)(runtimeGate, suppliedProof, args.gate_receipt_id);
@@ -1979,7 +2022,7 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                     }
                     if (toolName === 'marrow_ask') {
                         const query = requireString(args, 'query');
-                        const result = await withControlDeadline((signal) => (0, index_1.marrowAsk)(API_KEY, BASE_URL, { query }, SESSION_ID, FLEET_AGENT_ID, signal));
+                        const result = await withControlDeadline((signal) => (0, index_1.marrowAsk)(API_KEY, BASE_URL, { query }, SESSION_ID, FLEET_AGENT_ID, signal), { toolName: 'marrow_ask' });
                         try {
                             (0, guidance_cache_1.writeGuidanceCache)({
                                 apiKey: API_KEY,
@@ -1989,15 +2032,12 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                             });
                         }
                         catch { /* owner-only cache is best effort */ }
-                        success(id, {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        });
+                        toolSuccess(id, clientOperationalPayload('marrow_ask', result));
                         return;
                     }
                     if (toolName === 'marrow_status') {
-                        const result = await withControlDeadline((signal) => (0, index_1.marrowStatus)(API_KEY, BASE_URL, SESSION_ID, FLEET_AGENT_ID, signal), { cacheAware: false });
-                        const statusRecord = result;
-                        toolSuccess(id, { ...statusRecord, client_update: statusRecord.client_update || (0, request_reliability_1.localClientUpdate)() });
+                        const result = await withControlDeadline((signal) => (0, index_1.marrowStatus)(API_KEY, BASE_URL, SESSION_ID, FLEET_AGENT_ID, signal), { cacheAware: false, toolName: 'marrow_status' });
+                        toolSuccess(id, clientOperationalPayload('marrow_status', result));
                         return;
                     }
                     if (toolName === 'marrow_create_key') {
@@ -2135,7 +2175,7 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                         return;
                     }
                     if (toolName === 'marrow_runtime_status') {
-                        const result = await withControlDeadline((signal) => (0, index_1.marrowRuntimeStatus)(API_KEY, BASE_URL, args.fast !== false, SESSION_ID, FLEET_AGENT_ID, signal), { cacheAware: false });
+                        const result = await withControlDeadline((signal) => (0, index_1.marrowRuntimeStatus)(API_KEY, BASE_URL, args.fast !== false, SESSION_ID, FLEET_AGENT_ID, signal), { cacheAware: false, toolName: 'marrow_runtime_status' });
                         success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
                         return;
                     }
@@ -2191,9 +2231,9 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                                 : undefined,
                             period: args.period,
                         };
-                        const result = await withControlDeadline((signal) => (0, index_1.marrowAgentRuntime)(API_KEY, BASE_URL, runtimeInput, SESSION_ID, FLEET_AGENT_ID, signal), { highRisk: isHighRiskAction(runtimeInput.action, runtimeInput.type) });
+                        const result = await withControlDeadline((signal) => (0, index_1.marrowAgentRuntime)(API_KEY, BASE_URL, runtimeInput, SESSION_ID, FLEET_AGENT_ID, signal), { highRisk: isHighRiskAction(runtimeInput.action, runtimeInput.type), toolName: 'marrow_agent_runtime' });
                         storeRuntimeGuidance(result);
-                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        toolSuccess(id, clientOperationalPayload('marrow_agent_runtime', result));
                         return;
                     }
                     if (toolName === 'marrow_arbitrate') {
@@ -2391,12 +2431,12 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                         return;
                     }
                     if (toolName === 'marrow_handoff_status') {
-                        const result = await (0, index_1.marrowHandoffStatus)(API_KEY, BASE_URL, {
+                        const result = await withControlDeadline((signal) => (0, index_1.marrowHandoffStatus)(API_KEY, BASE_URL, {
                             status: args.status,
                             agentId: args.agentId || FLEET_AGENT_ID,
                             limit: args.limit,
-                        }, SESSION_ID, FLEET_AGENT_ID);
-                        success(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] });
+                        }, SESSION_ID, FLEET_AGENT_ID, signal), { cacheAware: false, toolName: 'marrow_handoff_status' });
+                        toolSuccess(id, clientOperationalPayload('marrow_handoff_status', result));
                         return;
                     }
                     if (toolName === 'marrow_session_end') {