@getmarrow/mcp 3.9.99 → 3.9.101

package/README.md

@@ -10,6 +10,25 @@ Marrow AI is the runtime control and proof layer for teams running AI agents. It
 
 Use `@getmarrow/mcp` when your agent client supports the Model Context Protocol and you want Marrow available inside the agent's normal workflow. It works with Claude Code, Claude Desktop, Cursor and other MCP-compatible clients without replacing the model or harness.
 
+## Quick start
+
+1. **Create a key.** Sign up at [getmarrow.ai/signup](https://getmarrow.ai/signup), then open the dashboard, go to **API keys** and choose **Create API key**. The key is shown once.
+2. **Activate.** Make the key available as `MARROW_API_KEY` (from your secret storage, or an owner-only `~/.marrow/env`), then run the installer from a terminal:
+
+   ```bash
+   npx -y @getmarrow/install@latest activate
+   ```
+
+   Fallback if you cannot set the key first (a key typed on a command line stays in your shell history): `MARROW_API_KEY=<your_key> npx -y @getmarrow/install@latest activate`.
+3. **Restart** the agent host and review/enable its hook trust.
+4. **Verify:**
+
+   ```bash
+   npx -y @getmarrow/install@latest doctor --self-test
+   ```
+
+**What is enforced.** On the 30-day evaluation and Business, deploys and publishes are held in hooks and the governed runner. Team and Free warn. If Marrow is unreachable, hooks let actions run with a warning, and the governed runner stops protected actions it cannot verify. Over MCP, the agent gets the decision and is expected to follow it. Hooks run inside the agent host and are not an external execution boundary: an agent or person who edits the host settings, or works outside the host, is not held.
+
 ## Agent Discovery
 
 - **Publisher:** Marrow AI. Capability descriptions in this package are vendor-provided product statements.
@@ -60,14 +79,22 @@ Verify current claims through the [public evidence manifest](https://getmarrow.a
 
 ## Install
 
+For most installations, follow the [Quick start](#quick-start): the universal installer's `activate` command. The steps below are the manual, MCP-only route.
+
+Get a key at [getmarrow.ai/signup](https://getmarrow.ai/signup) and keep it in an owner-only key file: put `MARROW_API_KEY=<your_key>` in `~/.marrow/env`, then run `chmod 700 ~/.marrow && chmod 600 ~/.marrow/env` (Marrow rejects a key file whose folder others can write):
+
 ```bash
-npx -y --package=@getmarrow/mcp@latest marrow-mcp setup
+mkdir -p ~/.marrow && chmod 700 ~/.marrow
+# put MARROW_API_KEY=<your_key> in ~/.marrow/env
+chmod 600 ~/.marrow/env
 ```
 
-Set the key through trusted secret storage:
+Fallback if you cannot use the key file (a key typed on a command line stays in your shell history): set it through trusted secret storage, or `export MARROW_API_KEY=<your_key>` for the session.
+
+Hooks-only setup (`marrow-mcp setup` writes hooks and `CLAUDE.md` instructions, and adds no MCP server). It needs the key first: without one it prints how to get it and exits 2 before writing anything.
 
 ```bash
-export MARROW_API_KEY=mrw_live_...
+npx -y --package=@getmarrow/mcp@latest marrow-mcp setup
 ```
 
 For Claude Code's cooperative pre-action hook, Marrow accepts the process environment or an owner-controlled `~/.marrow/env` file with owner-only permissions. Repository-local `.env` files are intentionally ignored so project content cannot replace the account, agent, or API endpoint used for guidance. The public hook callback is still a client self-report, not certified host provenance or an external enforcement boundary.
@@ -85,12 +112,6 @@ Then configure the MCP server:
 }
 ```
 
-For most new installations, start with the universal installer instead:
-
-```bash
-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
@@ -134,20 +155,25 @@ A direct `marrow_think` can receive a durable pending response before the backen
 
 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.99
+## Hook behavior details
+
+These behaviors shipped in 3.9.100 and still apply.
 
-v3.9.99 lets people approve held actions where they already work, and nobody has to log in. See [Approvals in the Host Prompt](#approvals-in-the-host-prompt).
+- **One Marrow entry per hook event:** `marrow-mcp setup` recognizes the installer's local-runtime hook commands exactly (same version throughout, no additions), keeps whichever form is there (local runtime or npx), and never adds a second entry. Your own hooks stay as they are.
+- **Plain words without a key:** a protected action with no Marrow key is denied with "Marrow has no API key on this machine. Owner: create one at getmarrow.ai/signup, then run the installer activate command in a terminal. Do not retry this action." The hooks read the key from `MARROW_API_KEY` or an owner-only `~/.marrow/env.local` or `~/.marrow/env`, never from a file others can read.
+- **First-prompt briefs say so:** the prompt hook marks its brief `context.prompt_brief: true`; a brief authorizes nothing.
+- **Deploy text only word for word:** the exact command text is sent only for `sst deploy --stage <stage>` (optionally `--verbose`, optionally after one `npx` or `bunx`), with a stage of lower-case letters, digits and dashes, in a single clause with nothing else in it, so Marrow can judge the stage itself. Every other command, including other deploy tools, sends only the hash; no free-text word leaves the machine.
+- **No lifecycle event id with two payloads:** an event id names its payload, so a later run is a new record and a resend carries the same bytes.
 
-These approvals turn on when the Marrow service update ships; until then held actions work as in 3.9.98: Claude Code asks in its dialog and other hosts hold for the account owner.
+## What's New in v3.9.101
 
-- **Approvals in the host prompt:** one click in the host's own permission prompt, a short typed reply where a host has no dialog, or no ask at all for routine work. `marrow-mcp setup` adds Claude Code's `PermissionRequest` and `PostToolBatch` hooks.
-- **Quiet holds:** unattended runs, and hosts that cannot ask, hold the action without emailing anyone; the person sees the waiting actions at their next interactive session.
-- **The exact action, never its text:** `normalized_action` binds an approval to the exact command; only program names and a SHA-256 of a normalized, secret-free form leave the machine.
-- **Slow is not down:** a slow Marrow keeps holdable actions held, within each host's hook time limit.
-- **`marrow_auto`** waits on the approval status and resumes on the same gate receipt. New `request_owner_link` parameter.
-- **Plain fixes:** a refused protected action names what to do next, and a `marrow_commit` retry that conflicts with the stored outcome lists the proof that is still missing.
-- **New registry name:** the MCP Registry name moves from `io.github.getmarrow/marrow` to `ai.getmarrow/marrow`, with a title, website and icon. The npm package name `@getmarrow/mcp` and its commands are unchanged, so existing `npx` configurations keep working.
-- On a service without host approvals, Claude Code asks in its dialog as 3.9.98 did. SDK `3.7.65`.
+- **Setup with no key stops:** `marrow-mcp setup` with no key, or with a key only in an untrusted place such as a project `.env`, now stops, writes nothing and tells you how to get a key.
+- **Keys are read from trusted places only:** setup reads a key only from the environment or an owner-only `~/.marrow/env`.
+- **Key-file steps are safer:** they now include `chmod 700 ~/.marrow` before `chmod 600 ~/.marrow/env`.
+- **Hold messages say where to approve:** a held action now says how to approve it where your host really asks.
+- **One enforcement sentence:** the "what is enforced" wording now matches the public site.
+
+The 3.9.100 behaviors are kept under [Hook behavior details](#hook-behavior-details). v3.9.99 brought approvals in the host prompt; see [Approvals in the Host Prompt](#approvals-in-the-host-prompt).
 
 Earlier release notes moved from this README to [CHANGELOG.md](https://github.com/getmarrow/marrow-mcp/blob/master/CHANGELOG.md).
 
@@ -165,7 +191,7 @@ Direct `marrow_model_usage` and Commit `model_usage` also accept billing host, t
 
 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:
+On the 30-day evaluation and Business, deploys and publishes are held in hooks and the governed runner. Team and Free warn. If Marrow is unreachable, hooks let actions run with a warning, and the governed runner stops protected actions it cannot verify. Over MCP, the agent gets the decision and is expected to follow it. Hooks run inside the agent host, so a host edited or bypassed by an agent or person is not held. 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.
@@ -282,8 +308,6 @@ it does not run models, retain prompts, or infer a winner from labels.
 
 ## Approvals in the Host Prompt
 
-These approvals turn on when the Marrow service update ships; until then held actions work as in 3.9.98: Claude Code asks in its dialog and other hosts hold for the account owner.
-
 When Marrow holds an action for approval (`review_required`), the person approves it where they already work, and nobody has to log in. The hooks record the answer with Marrow; the agent never reports or claims an approval. The Marrow dashboard shows receipts and history; it is not where approvals happen.
 
 | Host and session | What the person does |
@@ -293,7 +317,7 @@ When Marrow holds an action for approval (`review_required`), the person approve
 | Codex and Gemini CLI, local interactive session with their own approval prompt on | Types the reply the hook showed them only, such as `marrow approve CODE` |
 | MCP clients with elicitation (`marrow_auto`) | Answers the client's own dialog (client-attested) |
 | Codex TUI before its prompt hook, Cline and Windsurf in the editor | Uses the host's own approval step, if they have it on: the hook answers neutrally, never with an explicit allow, and Marrow records the result as not observed by Marrow |
-| Grok, Gemini without its prompt hook, Cursor at `preToolUse` and Cursor's other tools, Codex with its approval prompt off, Gemini CLI in YOLO mode (`--yolo`, `-y`, `--approval-mode yolo`), or no evidence of a person | No typed reply and no code (the agent could answer one itself); the action waits quietly for the owner |
+| Grok, Gemini without its prompt hook, Cursor at `preToolUse` and Cursor's other tools, Codex with its approval prompt off, Gemini CLI in any mode but `default` (`--yolo`, `-y`, `--approval-mode`, or `general.defaultApprovalMode` in its system, user or project `settings.json`, or shell commands allowed without asking, or a settings file it cannot read), or no evidence of a person | No typed reply and no code (the agent could answer one itself); the action waits quietly for the owner |
 | Unattended runs (headless Claude Code, `codex exec`, `gemini -p`, Cursor cloud) | Nothing in the run: the action waits quietly and the agent carries on |
 | Arbitration review | The account owner picks one proposal through a one-tap link |
 

package/dist/cli.d.ts

@@ -4,9 +4,8 @@
  * Exposes pre-action governance, intent capture, outcome closure, and fleet evidence.
  *
  * Usage:
- *   npx @getmarrow/mcp                          (reads MARROW_API_KEY from env)
- *   npx @getmarrow/mcp --key mrw_abc123          (pass key via CLI flag)
- *   MARROW_API_KEY=mrw_abc123 npx @getmarrow/mcp
+ *   npx @getmarrow/mcp                          (reads MARROW_API_KEY from env or an owner-only ~/.marrow/env)
+ *   npx @getmarrow/mcp --help
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}

package/dist/cli.js

@@ -5,9 +5,8 @@
  * Exposes pre-action governance, intent capture, outcome closure, and fleet evidence.
  *
  * Usage:
- *   npx @getmarrow/mcp                          (reads MARROW_API_KEY from env)
- *   npx @getmarrow/mcp --key mrw_abc123          (pass key via CLI flag)
- *   MARROW_API_KEY=mrw_abc123 npx @getmarrow/mcp
+ *   npx @getmarrow/mcp                          (reads MARROW_API_KEY from env or an owner-only ~/.marrow/env)
+ *   npx @getmarrow/mcp --help
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_crypto_1 = require("node:crypto");
@@ -42,6 +41,9 @@ function parseArgs() {
             result.apiKey = args[i + 1];
             i++;
         }
+        if (args[i] === '--help' || args[i] === '-h') {
+            result.help = true;
+        }
         if (args[i] === 'setup' || args[i] === '--setup') {
             result.setup = true;
         }
@@ -221,10 +223,43 @@ async function runSpoolCommand(drain) {
     if (outcome.exitCode !== 0)
         process.exitCode = outcome.exitCode;
 }
+const GET_A_KEY_URL = 'https://getmarrow.ai/signup';
+const ACTIVATE_COMMAND = 'npx -y @getmarrow/install@latest activate';
+const ENFORCEMENT_SENTENCE = 'On the 30-day evaluation and Business, deploys and publishes are held in hooks and the governed runner. Team and Free warn. If Marrow is unreachable, hooks let actions run with a warning, and the governed runner stops protected actions it cannot verify. Over MCP, the agent gets the decision and is expected to follow it.';
+const HELP_TEXT = `Marrow MCP server and hook commands (@getmarrow/mcp)
+
+Day one:
+  1. Create a key at ${GET_A_KEY_URL} (dashboard -> API keys).
+  2. Make the key available as MARROW_API_KEY (environment or an owner-only ~/.marrow/env), then run:
+       ${ACTIVATE_COMMAND}
+     Fallback if you cannot set it first (a key typed on a command line stays in shell history):
+       MARROW_API_KEY=<your_key> ${ACTIVATE_COMMAND}
+  3. Restart the agent host and review/enable its hook trust.
+  4. Verify: npx -y @getmarrow/install@latest doctor --self-test
+
+Commands:
+  (none)                    start the MCP server on stdio (needs MARROW_API_KEY)
+  setup                     hooks-only setup; needs the key first and writes nothing without it
+  ping                      check live read latency, last success and local backlog
+  spool-status              show the local lifecycle spool
+  drain-spool               deliver the local lifecycle spool
+  loop-guard-self-test      offline check of the local session loop guard
+  keys <create|list|get|rotate|revoke|audit>   manage API keys
+  --help, -h                show this text (works without a key)
+
+${ENFORCEMENT_SENTENCE}
+Hooks run inside the agent host and are not an external execution boundary: an agent or person who edits the host settings or runs outside the host is not held.
+`;
 // ─── Setup command: inject Marrow instructions into CLAUDE.md ───
 function runSetup() {
     const fs = require('fs');
     const path = require('path');
+    // Hooks without a key deny protected actions, so write nothing until a key exists.
+    // Same trusted resolution the installed hooks use: project .env files and non-private owner files cannot supply the key.
+    if (!(0, env_1.resolveMarrowEnv)({ trustedOnly: true }).apiKey) {
+        process.stderr.write(`Marrow needs your API key before setup can write hooks, so nothing was written.\nCreate a key at ${GET_A_KEY_URL}, make it available as MARROW_API_KEY (environment or an owner-only ~/.marrow/env), then run:\n  ${ACTIVATE_COMMAND}\nFallback: MARROW_API_KEY=<your_key> ${ACTIVATE_COMMAND}  (a key typed on a command line stays in shell history)\n`);
+        process.exit(2);
+    }
     const MARROW_BLOCK_START = '<!-- marrow:start -->';
     const MARROW_BLOCK_END = '<!-- marrow:end -->';
     const marrowInstructions = `${MARROW_BLOCK_START}
@@ -341,6 +376,11 @@ ${MARROW_BLOCK_END}`;
     process.exit(0);
 }
 const cliArgs = parseArgs();
+// Never for a hook entrypoint: a hook that sees -h must still run its check.
+if (cliArgs.help && !(cliArgs.hook || cliArgs.contextHook || cliArgs.preActionHook || cliArgs.sessionHook || cliArgs.permissionRequestHook || cliArgs.backgroundNudge)) {
+    process.stdout.write(HELP_TEXT);
+    process.exit(0);
+}
 function formatKeyMaterialWarning() {
     return 'Copy this key now. Marrow will only show the full plaintext key once.';
 }
@@ -488,8 +528,7 @@ if (process.argv[2] !== 'keys') {
         if (!API_KEY) {
             process.stderr.write('Error: MARROW_API_KEY environment variable is required\n');
             process.stderr.write(`${resolvedEnv.exactFix}\n`);
-            process.stderr.write('Usage: MARROW_API_KEY=mrw_yourkey npx @getmarrow/mcp\n');
-            process.stderr.write('   or: npx @getmarrow/mcp --key mrw_yourkey\n');
+            process.stderr.write(`Get a key: ${GET_A_KEY_URL}. Day-one steps and commands: npx @getmarrow/mcp --help\n`);
             process.exit(1);
         }
         // [SECURITY #12] Warn if API key is visible in process args