@getmarrow/mcp 3.9.82 → 3.9.84

package/README.md

@@ -87,6 +87,14 @@ For most new installations, start with the universal installer instead:
 npx @getmarrow/install activate
 ```
 
+After setup writes MCP configuration or hooks, restart the agent host and review/enable its hook trust. Then verify the reloaded environment:
+
+```bash
+npx -y @getmarrow/install@latest doctor --self-test
+```
+
+Successful setup alone does not mean this process reloaded or that hooks are active. Keep savings at zero until observed usage supplies evidence.
+
 ## Tool Profiles
 
 Ordinary setup does not require `MARROW_TOOL_PROFILE`. When the variable is unset, Marrow uses the `primary` profile and exposes exactly the 17 tools in [Primary MCP Tools](#primary-mcp-tools).
@@ -116,7 +124,23 @@ 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.82
+## Pending write recovery
+
+A direct `marrow_think` can receive a durable pending response before the backend can safely expose a decision ID. The client recognizes the explicit `agent_write_reconciliation.v1` think contract and the corresponding current legacy pending shapes. It retries the identical authenticated request with the original idempotency key, agent and session, at most three reconciliation rounds with the existing one-second wait between rounds. Each round retains up to two transport attempts for retryable failures, so one invocation can send up to six HTTP requests, all with the same key and body. It never creates a placeholder decision or starts an automatic operation to recover a direct think call. Unknown states, conflicting keys and unsafe responses fail closed; exhaustion returns a retryable structured `pending_receipt` with `committed:false`, the original `idempotency_key`, and `request_hash`. To resume manually, pass both fields to `marrow_think` with the same arguments, credentials, agent and session. The hash binds that exact canonical request and scope; drift is rejected before sending. No prompt, credential, or raw scope is included in the receipt. Caller keys must be privacy-safe opaque identifiers.
+
+A saved `observed_unverified` outcome is terminal observation evidence, not a committed outcome. Receipt expiry cannot retroactively authorize completed work. Preserve the original decision, receipt, proof and key; an already authorized durable checkpoint may finish through its existing exact recovery path. Do not repeat the action merely to obtain a fresh receipt.
+
+## What's New in v3.9.84
+
+v3.9.84 adds bounded direct-think recovery without inventing a decision ID, and an exact scoped pending receipt for manual continuation. Saved unverified observations remain terminal untrusted evidence. It also preserves confirmation of pending automatic writes by replaying the same authenticated operation and request, with one retry owner and a four-second attempt ceiling inside the unchanged eight-second total budget. Numeric and date-based server retry delays are preserved. Conflicting receipts never confirm closure, and unavailable or unverified results remain pending.
+
+Post-action commit lookup now preserves the original general/empty-surface defaults and optional explicit target. It remains observation-only. Receipt expiry retains unverified observation evidence unless an existing historically authorized checkpoint supports exact recovery; it does not extend the old receipt or grant retrospective permission. Transient lifecycle delivery retries preserve the queued event and its stable identity across restart within bounded scheduling and attempt limits. Queued, server-accepted, and committed remain separate facts.
+
+Before upgrading, finish existing pending auto operations with their current verified client. Older auto requests omitted supplied surfaces from think; correcting nonempty surfaces can therefore expose an idempotency conflict for that old operation. Do not reinterpret the conflict, open a replacement operation, use a silent legacy fallback, or automatically downgrade. Omitted/empty surface operations preserve their original canonical scope. This is a scope-correctness change, not a promise that every pending old-client operation can resume across an upgrade.
+
+Default primary guidance uses runtime followed by commit and exposes exactly 17 tools. Auto remains available in explicitly selected core/full profiles. SDK `3.7.62` and installer `0.1.56` are unchanged; install MCP `3.9.84`, reload the host, review hook trust, and verify before claiming the updated client is active.
+
+### Previous release: v3.9.82
 
 v3.9.82 batches client reliability fixes for `marrow_auto`. Continuations honor the server's finite retry delay within the existing eight-second core budget; when the delay cannot fit, the same operation remains pending with retry guidance. Gated auto reuses the server-created decision after checking its canonical scope, and ordinary owner approval can resume that decision when the backend explicitly declares the supported proof contract. The installed bytes of v3.9.81 cannot provide these client changes; update MCP for this behavior. SDK and installer versions are unchanged.
 
@@ -128,7 +152,7 @@ v3.9.81 adds bounded structured failure evidence to the authenticated eleven-too
 
 ### Previous release: v3.9.80
 
-v3.9.80 is a reliability patch for direct `marrow_think` and `marrow_commit` calls. Each invocation now carries one stable bounded idempotency key. Only the backend's documented pending-persistence states are reconciled, using the byte-identical request and key after a fixed one-second delay for at most three total attempts. A 202 response is never reported as successful completion; unknown, malformed, correlation-drifted, or exhausted pending responses fail closed with a structured error. Explicit caller-supplied idempotency keys remain unchanged, and durable `observed_unverified` outcomes retain their terminal, non-authorizing semantics.
+v3.9.80 is a reliability patch for direct `marrow_think` and `marrow_commit` calls. Each invocation now carries one stable bounded idempotency key. Only the backend's documented pending-persistence states are reconciled, using the byte-identical request and key after a fixed one-second delay for at most three reconciliation rounds. The existing transport layer permits up to two attempts per round, for up to six HTTP requests with the same key and body. A 202 response is never reported as successful completion; unknown, malformed, correlation-drifted, or exhausted pending responses fail closed with a structured error. Explicit caller-supplied idempotency keys remain unchanged, and durable `observed_unverified` outcomes retain their terminal, non-authorizing semantics.
 
 ### Previous release: v3.9.79
 
@@ -168,7 +192,7 @@ v3.9.71 makes the advertised Grok control loop true:
 - Grok native PreToolUse, PostToolUse/PostToolUseFailure, and nonblocking Stop hooks provide bounded client-reported gating, result evidence, and one turn closeout. The governed wrapper remains an explicit bounded fallback;
 - idle spool nudge drains up to 40 current-namespace events so the queue does not sit as a nag;
 - if `risk_gate.enforced` is false, the gate is advisory — do not describe it as a live block;
-- `marrow_commit.decision_id` comes from `marrow_think`, `marrow_auto`, or an arbitration runtime that actually created a decision. A normal runtime authorization is a gate receipt, not a decision.
+- `marrow_commit.decision_id` comes from `marrow_think`, `marrow_auto`, or an arbitration runtime that actually created a decision. A normal runtime may create or reuse a decision: follow runtime.decision_id and completion_contract. Keep runtime.runtime_authorization.id separate as gate_receipt_id.
 
 ## Previous: v3.9.69
 
@@ -385,25 +409,29 @@ Client hook activity alone never produces certified coverage percentages. An ins
 
 ## Governed Action Flow
 
+With `MARROW_TOOL_PROFILE` unset, the default primary profile uses `marrow_agent_runtime` followed by `marrow_commit`. It exposes 17 tools; `marrow_auto` is available only after an explicit `core` or `full` selection and MCP restart. Primary status and lessons use `marrow_agent_status` and `marrow_fleet_lessons`.
+
 Configured hooks can provide cooperative telemetry and context, but they are not a certified execution boundary. Before deploys, merges, publishes, migrations, credential changes, financial operations, or customer-impacting work:
 
 1. Call `marrow_agent_runtime` or `marrow_decision_brief`.
 2. Stop when the returned decision is `block` or `review_required`; otherwise follow its prior lesson and proof contract.
-3. Reuse a server-created runtime `decision_id` when the completion contract identifies it. Call `marrow_think` or `marrow_auto` when decision creation is still required. Keep `marrow_agent_runtime.runtime_authorization.id` separate as the gate receipt for consequential work.
+3. Reuse a server-created runtime `decision_id` when the completion contract identifies it. Call `marrow_think` when decision creation is still required; explicitly selected core/full profiles can also use `marrow_auto`. Keep `marrow_agent_runtime.runtime_authorization.id` separate as the gate receipt for consequential work.
 4. Perform the action only when its gate allows it. Codex, Grok, and Gemini use configured native hooks only after restart and host hook review. The governed wrapper remains an explicit bounded fallback: `npx @getmarrow/install run --agent <agent-id> -- -- <command>`.
 5. Call `marrow_commit` with that `decision_id`, the outcome, gate receipt, and required proof.
 
-`marrow_agent_runtime` returns `runtime_authorization` with the authoritative gate receipt. An ordinary or arbitrated runtime that creates a decision also returns its server-created `decision_id`; follow `completion_contract.decision_creation_required` and preserve the returned scope. When decision creation is required, call `marrow_think` or use `marrow_auto`. Auto requests the existing expanded runtime response to check receipt identity, decision, action, agent, session, and expiry before reusing that decision; it does not obtain a second authorization fetch.
+`marrow_agent_runtime` returns `runtime_authorization` with the authoritative gate receipt. An ordinary or arbitrated runtime that creates a decision also returns its server-created `decision_id`; follow `completion_contract.decision_creation_required` and preserve the returned scope. When decision creation is required, call `marrow_think`; core/full can also use `marrow_auto`. Auto requests the existing expanded runtime response to check receipt identity, decision, action, agent, session, and expiry before reusing that decision; it does not obtain a second authorization fetch.
 
 A `review_required`, `block`, or `outcome_observation_only` result never permits the action. If the action already occurred and its real result must be preserved, `marrow_commit` can ask runtime to bind observation delivery to the existing decision, action, session, and agent. The exact backend `outcome_observation_only` correlation is non-durable and non-authorizing, so MCP never sends it as a gate, arbitration, or owner-approval receipt. An accepted observation reports `committed: false`, `outcome_state: "observed_unverified"`, `authorization_granted: false`, and `trusted_learning_applied: false`, plus the backend's `exact_next_action`. This is durable delivery, so do not retry or spool the same observation. To promote it into trusted learning, obtain the named authorization and proof, then make an explicit new commit attempt using the exact observed payload. Never synthesize a decision, receipt, approval, or authorization.
 
-`marrow_auto` returns an `operation_id`, phase, and resumable state. For a resumable pending phase, respect `retry_after_ms` and use the same operation ID and unchanged scope; auto never shortens the requested finite delay to fit its core budget. When the phase is `proof_required`, supply the requested measured evidence before retrying that operation. Stable phase idempotency keys preserve the original decision and outcome across retries; the backend remains authoritative for acceptance and conflicts.
+`marrow_auto` returns an `operation_id`, phase, and resumable state. For a resumable pending phase, respect `retry_after_ms` and use the same operation ID, tenant, agent, session, action, type, surfaces, outcome, proof and receipt payload; auto never shortens the requested finite delay to fit its core budget. When the phase is `proof_required`, supply the requested measured evidence before retrying that operation. Stable phase idempotency keys preserve the original decision and outcome across retries; the backend remains authoritative for acceptance and conflicts. A four-second automatic write attempt ceiling leaves replay time inside the existing eight-second total budget. Long server delays remain pending without waiting beyond that budget. Malformed or unbounded Retry-After headers stop automatic continuation. Only committed:true confirms closure; pending is not evidence that a server write failed.
+
+If a receipt expires while the same decision remains open, explicitly request normal runtime again with the original action, type, surfaces, agent and session. A fresh request key is required: replaying the old runtime key replays its old receipt. Verify the returned `runtime.decision_id` still matches the original, keep the new `runtime.runtime_authorization.id` as `gate_receipt_id`, and satisfy the current proof and approval contract. For a scope with an explicit target, use the `marrowAgentRuntime` library or `POST /v1/agent/runtime` preserving that target; the public MCP runtime schema does not expose target. Do not renew through post-action `auto_gate`: it only obtains observation truth. A fresh receipt never retrospectively authorizes an action taken without permission, and a changed scope is a different decision. Expired or used receipts may return an accepted `observed_unverified` result with `committed:false`; that is not closure.
 
 For an ordinary gate, continue only when the server declares `completion_contract.owner_approval.mode: "ordinary_non_arbitrated"`. Auto waits in `owner_approval_required` until the caller actually obtains explicit owner approval for the exact work and supplies `proof.owner_approval = { approved_by: "owner", reference: "approved-release-bundle" }` together with required measured proof. Then call auto once with the same operation ID and original decision/receipt scope. The object records actual approval; it is not permission to infer approval from action text, a model response, or `human_directed`. Unknown ordinary completion contracts remain stopped without automatically starting arbitration. The backend checks receipt ownership, scope, expiry, and proof before confirming closure.
 
 For arbitration, the ordinary proof marker is not accepted. Approve the exact arbitration decision in the authenticated Marrow dashboard, then call auto with the same operation ID, `arbitration_receipt_id`, and server-issued `owner_approval_receipt_id`. Proof or chat text cannot substitute for this dashboard receipt. A CLI closed response reports `phase: "closed"`, `live_delivery.committed: true`, and `resumable: false`; the library result uses `committed: true`. Neither an ordinary marker nor an outcome record changes a stopped action into an allowed action.
 
-The CLI's lifecycle `receipt.queued: true` means its stable event is stored locally for later bounded delivery; `receipt.accepted: false` must not be read as server acceptance. Process exit can interrupt the background nudge, leaving the event for a later run. `phase_timings_ms.total` measures core auto phases. `response_timings_ms` contains numeric `core`, `durable_enqueue`, and `full_response`; the last ends at response construction and excludes subsequent stdout drain and host processing. Canary `latency_ms` independently measures the MCP round trip, while `attempts` and `retry_wait_ms` describe measured outer tool retries, not internal database or network calls.
+The CLI's lifecycle `receipt.queued: true` means its stable event is stored locally for later bounded delivery; `receipt.accepted: false` must not be read as server acceptance. Transient failures preserve the queued event and retry schedule for later bounded delivery, including after restart. Server retry guidance is respected. Authentication and terminal delivery errors remain failed with explicit repair guidance. Process exit can interrupt the background nudge, leaving the event for a later run. `phase_timings_ms.total` measures core auto phases. `response_timings_ms` contains numeric `core`, `durable_enqueue`, and `full_response`; the last ends at response construction and excludes subsequent stdout drain and host processing. Canary `latency_ms` independently measures the MCP round trip, while `attempts` and `retry_wait_ms` describe measured outer tool retries, not internal database or network calls.
 
 Example pre-action request:
 

package/dist/cli.js

@@ -165,17 +165,21 @@ Use Marrow according to the capability evidence returned by the MCP server:
 
 1. **MCP baseline is on demand:** MCP transport exposes tools; it does not provide passive hooks. Public hook callbacks and local configuration are client-self-reported activity, not certified coverage.
 2. **Before risky actions:** Respect the returned \`allow\`, \`warn\`, \`review_required\`, or \`block\` decision and its proof contract. Call \`marrow_agent_runtime\` explicitly when verified passive coverage cannot cover the action.
-3. **After meaningful work:** Record the real success or failure with \`marrow_commit\` or \`marrow_auto\`. A tool exit or session end is not proof that the business outcome succeeded.
+3. **After meaningful work:** Record the real success or failure with \`marrow_commit\`; \`marrow_auto\` is available only in explicitly selected core/full profiles. A tool exit or session end is not proof that the business outcome succeeded.
 4. **Unfinished work:** Leave pending outcomes visible. Do not invent success to clear a closure item.
 5. **To explain an intervention:** Use \`marrow_decision_trace\`, then relay its \`intervention_receipt\` in one factual sentence when Marrow blocked, warned, or required review. Stay quiet for routine low-risk work.
-6. **To query authorized history:** Call \`marrow_ask("plain english question")\` — ask what failed, what worked, and what policy should apply.
+6. **To query authorized history:** Use \`marrow_fleet_lessons\` in the default primary profile; core/full provide \`marrow_ask\` for authorized history.
 7. **When an update is reported:** Tell the operator and use the returned exact update and verification commands only when local change policy permits. Never silently change packages or configuration.
 
 Do not skip the gate or outcome. Marrow's value comes from controlling the action before execution and preserving evidence afterward.
 
 Capability boundaries: configured native hooks provide cooperative client-reported control and lifecycle evidence only; \`createPassiveRuntime().install()\` covers only its owned Node process while installed; a governed wrapper covers only its wrapped command; and a custom host needs a bounded event adapter. A model name, host label, API key, public hook entrypoint, installed configuration, or client-self-reported callback is not proof of coverage or enforcement. Codex, Grok, and Gemini use configured native hooks only after restart and the host's hook review; the governed wrapper remains an explicit bounded fallback.
 
-For bounded outcome capture: \`marrow_auto({ action: "did X", outcome: "result Y", success: true })\`. One outer invocation normally completes think and commit in-band within its bounded client budget. If the host or network deadline is reached, retry with the returned \`operation_id\`; Marrow continues the same operation and never opens a second decision.
+With MARROW_TOOL_PROFILE unset, use the 17-tool primary runtime → commit flow. Reuse runtime.decision_id when its completion_contract identifies a created decision; keep runtime.runtime_authorization.id separate as gate_receipt_id. Use marrow_think only when decision creation is required. Explicit core/full profiles also expose marrow_auto: continue a pending response only after retry_after_ms with the same operation_id and unchanged scope, outcome, proof, and receipts. Only committed:true confirms closure; queued lifecycle delivery is separate.
+
+For an expired receipt, preserve the original decision, proof and idempotency key. Only an existing historically authorized checkpoint can support exact recovery. Otherwise an accepted observed_unverified result is terminal untrusted evidence: do not repeat the action, create a new decision, or renew permission retrospectively. Only committed:true confirms trusted learning.
+
+After authorized setup via \`npx -y --package=@getmarrow/mcp@latest marrow-mcp setup\`, reload the host, review/enable hook trust, then run \`npx -y @getmarrow/install@latest doctor --self-test\`. Configuration alone does not prove runtime coverage; empty savings remain zero until observed usage exists.
 ${MARROW_BLOCK_END}`;
     let dir = process.cwd();
     let claudeMdPath = null;
@@ -824,6 +828,8 @@ if (process.argv[2] !== 'keys') {
                 inputSchema: {
                     type: 'object',
                     properties: {
+                        idempotency_key: { type: 'string', description: 'Original privacy-safe pending receipt key when resuming the identical think request.' },
+                        request_hash: { type: 'string', description: 'Pending receipt request_hash; validates unchanged arguments, credentials, agent and session before resuming.' },
                         action: { type: 'string', description: 'What the agent is about to do' },
                         type: {
                             type: 'string',
@@ -868,9 +874,10 @@ if (process.argv[2] !== 'keys') {
                         gate_receipt_id: { type: 'string', description: 'Canonical receipt id from marrow_agent_runtime.runtime_authorization.id for risky work.' },
                         arbitration_receipt_id: { type: 'string', description: 'Required for arbitrated work: use marrow_arbitrate.arbitration.receipt_id from the same runtime response.' },
                         owner_approval_receipt_id: { type: 'string', description: 'Single-use owner approval receipt issued by authenticated dashboard review for review_required arbitration.' },
-                        action: { type: 'string', description: 'Optional original action. If provided and gate_receipt_id is omitted, MCP can fetch a matching runtime gate receipt before commit.' },
-                        type: { type: 'string', description: 'Optional original action type for auto gate lookup, e.g. deploy, publish, merge, handoff, implementation.' },
-                        surfaces: { type: 'array', items: { type: 'string' }, description: 'Optional surfaces for auto gate receipt, e.g. github, cloudflare, npm, production.' },
+                        action: { type: 'string', description: 'Optional exact original action for post-action observation lookup. This lookup cannot renew execution authority.' },
+                        target: { type: 'string', description: 'Exact original target, if supplied when the decision was created.' },
+                        type: { type: 'string', description: 'Exact original action type for observation lookup; defaults to general.' },
+                        surfaces: { type: 'array', items: { type: 'string' }, description: 'Exact original surfaces for observation lookup; omitted and empty both mean no surfaces.' },
                         auto_gate: { type: 'boolean', description: 'If true/default and action is provided, fetch runtime truth bound to this existing decision. Authorizing receipts preserve normal closure; exact outcome_observation_only correlation can submit only an observed_unverified result and is omitted from receipt evidence.' },
                         model_usage: { type: 'object', description: 'Optional compact token/cost/latency counts. Do not include raw prompts or completions.' },
                     },
@@ -1935,7 +1942,7 @@ if (process.argv[2] !== 'keys') {
                         capabilities: { tools: {}, prompts: {} },
                         serverInfo: { name: 'marrow', version: hook_contract_2.MCP_ADAPTER_VERSION },
                         ...(AUTO_ENROLL ? {
-                            instructions: `Call marrow_think before meaningful work to create the decision_id. Use marrow_agent_runtime before consequential actions and obey fresh allow/warn/review_required/block only when risk_gate.enforced is true; if enforced is false the gate is advisory, not a live block. Use marrow_ask for relevant prior lessons, and close outcomes with marrow_commit using that decision_id. 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. ${(0, host_capability_1.hostCapabilityInstructions)(hostCapability)}`,
+                            instructions: `Use marrow_agent_runtime before consequential actions and follow its gate, proof and approval contract. Reuse runtime.decision_id when completion_contract identifies a created decision; keep runtime.runtime_authorization.id separate as gate_receipt_id. Call marrow_think only when decision creation is required. Close outcomes with marrow_commit; only committed:true confirms closure. ${activeToolProfile() === 'primary' ? 'The default primary profile exposes 17 tools. Use marrow_agent_status for status and marrow_fleet_lessons for prior lessons.' : 'This explicitly selected core/full profile also provides marrow_auto, marrow_status and marrow_ask. Resume pending auto only after retry_after_ms with the same operation_id and unchanged scope, outcome, proof and receipts.'} An advisory risk_gate.enforced:false is not live enforcement; review_required or block still does not grant permission. Infrastructure failures are not policy denials; continue only low-risk reversible work from returned outage-safe guidance and require a fresh gate for high-risk work. ${(0, host_capability_1.hostCapabilityInstructions)(hostCapability)}`,
                         } : {}),
                         _meta: { host_capability: hostCapability },
                     });
@@ -2009,7 +2016,7 @@ When runtime/status returns a client_update notice, tell the operator and use it
 
 ## Outcome closure
 
-A successful command or tool exit is not proof that the business outcome succeeded. After meaningful work, close the real outcome with marrow_commit or marrow_auto and include success or failure plus the required evidence. If the result is unknown, leave it pending. Never invent success to clear a closure item.
+A successful command or tool exit is not proof that the business outcome succeeded. After meaningful work, use the default primary runtime → marrow_commit flow and include success or failure plus required evidence. Reuse runtime.decision_id and keep runtime.runtime_authorization.id separate as gate_receipt_id. Explicit core/full profiles also expose marrow_auto; resume pending only after retry_after_ms with the same operation_id and unchanged scope/body. Only committed:true confirms closure. If the result is unknown, leave it pending. Never invent success to clear a closure item.
 
 Use marrow_decision_trace when you need to explain why Marrow changed an action. Its intervention_receipt packages the relevant gate, required workflow, permit follow-through, proof, and recorded outcome without raw context, proof values, or another tenant's data. After a meaningful intervention, relay one factual receipt summary to the operator. Stay quiet for routine low-risk work.
 
@@ -2083,7 +2090,7 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                             human_directed: args.human_directed,
                             instruction_ref: args.instruction_ref,
                             source_meta: args.source_meta,
-                        }, SESSION_ID, FLEET_AGENT_ID);
+                        }, SESSION_ID, FLEET_AGENT_ID, undefined, { idempotencyKey: args.idempotency_key, requestHash: args.request_hash });
                         // Refresh orient warnings every 5th think call
                         thinkCallCount++;
                         if (thinkCallCount % 5 === 0) {
@@ -2125,6 +2132,7 @@ Marrow is not a replacement agent or a standalone memory app. Context and prior
                             arbitration_receipt_id: args.arbitration_receipt_id,
                             owner_approval_receipt_id: args.owner_approval_receipt_id,
                             action: args.action,
+                            target: args.target,
                             type: args.type,
                             surfaces: args.surfaces,
                             auto_gate: args.auto_gate,