@getmarrow/install 0.1.20 → 0.1.21

package/README.md

@@ -9,65 +9,24 @@ npx @getmarrow/install --dry-run
 npx @getmarrow/install --yes
 npx @getmarrow/install --repair
 npx @getmarrow/install doctor
-npx @getmarrow/install fleet
 ```
 
-## What's New in v0.1.20
+## What's New in v0.1.21
 
-v0.1.20 adds the Fleet Operator TUI for teams running multiple agents under one Marrow account.
+v0.1.21 makes token value proof part of the default install path.
 
-- `npx @getmarrow/install fleet` opens a terminal operator view when run in a real TTY.
-- CI/headless agents can use `npx @getmarrow/install fleet --no-interactive` for a stable text snapshot or `--json` for machine-readable status.
-- The view shows live agents, active workflows, risky actions waiting for proof, failed/stale outcomes, backpressure/capacity status, recent decisions, degraded hooks, and deploy/publish/merge gate posture.
-- Operators can press Enter to inspect an agent and print the exact fix command when hooks, outcome closure, or status coverage is degraded.
-- The command reads existing Marrow account endpoints and degrades gracefully when a route is unavailable, so it is safe to use during incidents.
+- Generated passive runtimes enable compact model-usage capture by default with `captureModelUsage`.
+- First-run self-test calls `/v1/agent/value/proof` and prints a `Token value proof` block.
+- Fresh accounts show token capture as active and warming up; accounts with observed model calls show calls, tokens, estimated savings, confidence, and next action.
+- Provider usage capture stores compact metadata only: provider, model, token counts, latency, cost estimate, workflow/decision linkage, and Marrow intervention type.
+- Marrow does not store prompts, completions, tool stdout/stderr, plaintext API keys, or raw model output for this feature.
+- Disable only when required with `MARROW_PASSIVE_TOKEN_USAGE=false`.
 
-Example:
+Business value: new users should see from day one whether Marrow is capturing the signals needed to prove token/time savings over workflows, tasks, and builds.
 
-```bash
-MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install fleet
-MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install fleet --no-interactive
-MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install fleet --json
-```
-
-## What's New in v0.1.14
-
-v0.1.14 adds adaptive governance mode recommendations without silent auto-switching.
-
-- `npx @getmarrow/install govern` now detects project signals such as `package.json`, deploy/publish scripts, `wrangler` config, GitHub workflows, migrations, Cursor/Codex/Claude files, and MCP config.
-- When `MARROW_API_KEY` is present, the TUI asks Marrow for a recommended mode: `passive`, `pilot`, or `enforce`.
-- The TUI shows the exact reasons, confidence, and selected command before the user applies anything.
-- User choice is explicit. Marrow logs whether the recommendation was accepted or overridden, but it does not silently switch modes.
-- Policy profiles are supported by the backend/SDK/MCP so businesses can define rules like local=passive, staging=pilot, production deploys=enforce.
-
-Example recommendation:
-
-```text
-Recommended mode: pilot
-Reason:
-- Node project detected
-- Cloudflare Worker detected
-- GitHub workflow detected
-- No owner approval policy configured yet
-```
-
-## What's New in v0.1.13
-
-v0.1.13 turns `npx @getmarrow/install govern` into an interactive terminal setup flow when run in a real TTY.
-
-- Select Codex, Claude Code, Cursor, OpenCode, OpenClaw, CI scripts, or a custom command with arrow keys.
-- Choose passive setup, governed pilot mode, or governed enforce mode.
-- Run passive setup + self-test from the TUI after explicit confirmation.
-- Check Marrow status and test the before-action gate from the same screen.
-- Print the exact command for the selected harness/mode so users know what to run next.
-- Exit cleanly with `q`, `Esc`, or `Ctrl+C`.
-- CI/non-TTY usage remains stable with `npx @getmarrow/install govern --no-interactive`.
+## Governed Runner
 
-This keeps Marrow passive-first: install once, verify Marrow is active, then let agents use the runtime/gate path automatically for risky work.
-
-## What's New in v0.1.12
-
-v0.1.12 adds the Marrow governed runner for businesses that want agent governance without replacing their existing harness.
+The Marrow governed runner is for businesses that want agent governance without replacing their existing harness.
 
 - `npx @getmarrow/install govern` prints a setup panel for detected harnesses and recommended protected commands.
 - `npx @getmarrow/install run --agent <agent-id> -- <command>` wraps existing agent, deploy, merge, publish, migration, and verification commands with Marrow's pre-action runtime gate.
@@ -86,12 +45,6 @@ Preview the detected harnesses and protected command examples:
 npx @getmarrow/install govern
 ```
 
-In a real terminal, this opens the interactive setup flow. In CI or scripts, use:
-
-```bash
-npx @getmarrow/install govern --no-interactive
-```
-
 Run a harmless command through Marrow:
 
 ```bash
@@ -117,15 +70,6 @@ MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run \
 
 Use `--policy warn` for pilot mode and `--fail-open` only for non-production local workflows where Marrow should never block execution.
 
-## What's New in v0.1.10
-
-- First-run output now explains the value in agent/user language: your agent is no longer starting from zero.
-- Self-test prints first proof: setup decision captured, outcome closed, runtime gate active, and risky work now gets a pre-action brief.
-- Fresh accounts get a guided prompt to try immediately: "I am about to deploy to production. What should I check first?"
-- Existing accounts/fleets show stronger proof when available: avoided mistakes, reused winning decisions, prevented risky actions, and token/time savings.
-- Generated SDK passive runtime now fails soft if `@getmarrow/sdk` is missing and the installer prints the exact dependency fix.
-- Docs now make the universal installer the default path; SDK and MCP are advanced/manual integration paths.
-
 ## Which Install Path Should I Use?
 
 Start here unless you already know you need a lower-level integration:
@@ -158,7 +102,9 @@ Expected result:
 - `/v1/agent/status` confirms capture health and missing hooks.
 - `/v1/agent/runtime` verifies the one-call runtime gate and returns the before-action intervention contract.
 - `/v1/agent/first-value` returns the five-minute proof payload used by installer, SDK, and MCP clients.
+- `/v1/agent/value/proof` returns token value proof from passive model-usage capture.
 - The installer prints: "Your agent is no longer starting from zero."
+- The installer prints: "Token value proof" with capture status, observed model calls, token totals, estimated savings, confidence, and exact next action.
 - Fresh accounts get a first useful action to try immediately.
 - Accounts with history get proof such as avoided mistakes, reused winning decisions, prevented risky actions, or estimated time/token savings.
 
@@ -172,39 +118,6 @@ I am about to deploy to production. What should I check first?
 
 Marrow should answer with `proceed`, `warn`, `block`, or `owner_approval_required`, plus required proof and matching fleet lessons/playbooks before the agent acts. This is the first product moment: not just "hooks installed", but "the agent is being warned before risky work."
 
-## Fleet Scale Startup Guidance
-
-For business fleets, agents can read `GET /v1/agent/scale/capacity-contract` after install or during startup. The capacity contract tells the agent whether the account is under backpressure, when low-risk runtime guidance can be reused, when high-risk actions must still call Marrow, and how to batch low-risk telemetry through `/v1/agent/ingest/batch`.
-
-This keeps Marrow passive without making it chatty. The current contract models the common `50 businesses x 50 agents = 2,500 agents` rollout shape and gives agents an exact next action: cache low-risk runtime guidance briefly, batch command/tool telemetry, and preserve proof-gated checks for deploys, publishes, merges, migrations, secrets, billing, and destructive work.
-
-## Fleet Operator TUI
-
-Use the operator TUI when a human owner or orchestrator agent needs to understand fleet health before acting:
-
-```bash
-MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install fleet
-```
-
-It shows:
-
-- live agents and selected agent inspection
-- active workflows
-- risky actions waiting for proof
-- failed or stale outcomes
-- backpressure and capacity guidance
-- recent decisions
-- degraded hooks
-- deploy, publish, and merge gate status
-- exact fix commands for common degraded states
-
-For automated reports or headless agents:
-
-```bash
-MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install fleet --no-interactive
-MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install fleet --json
-```
-
 ## What It Detects
 
 - OpenClaw-style workspaces
@@ -237,7 +150,7 @@ npx @getmarrow/install --md --dry-run
 
 ## Self-Test
 
-When `MARROW_API_KEY` is present, the installer creates a harmless test decision, commits the outcome, reads `/v1/agent/status`, calls the one-call runtime, and prints the first useful Marrow signal.
+When `MARROW_API_KEY` is present, the installer creates a harmless test decision, commits the outcome, reads `/v1/agent/status`, calls the one-call runtime, reads `/v1/agent/value/proof`, and prints the first useful Marrow signal plus token value proof.
 
 ```bash
 MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install --yes
@@ -271,6 +184,34 @@ npm install @getmarrow/sdk
 
 The generated runtime now fails soft with an explicit warning if the SDK package is missing, so onboarding does not crash a user process.
 
+## Passive Token Value Proof
+
+Token value proof is default-on when the installer writes `.marrow/passive-runtime.mjs`.
+
+In supported Node/TypeScript agents, the SDK passive runtime wraps outbound model-provider `fetch` responses and captures compact `usage` blocks when providers return them. MCP and harness integrations can also attach `model_usage` to `marrow_commit` or call `marrow_model_usage` when the harness exposes usage metadata.
+
+Captured fields are intentionally narrow:
+
+- provider and model
+- input, output, cached, and total token counts
+- optional cost and latency estimates
+- agent, workflow, session, and decision linkage
+- Marrow intervention type, such as `runtime_gate`, `proof_pack`, or `before_you_act`
+
+Marrow does not capture prompt text, completion text, raw tool output, command output, full environment values, or plaintext secrets for token value proof.
+
+Disable capture only when a project requires it:
+
+```bash
+MARROW_PASSIVE_TOKEN_USAGE=false
+```
+
+Day-one behavior:
+
+- Fresh install: `Token usage capture is ready; no model calls have been reported yet.`
+- After observed usage: Marrow reports model calls, total tokens, estimated tokens saved, confidence, trend, and next action.
+- After workflows complete: agents should show the returned `token_value_signal` or value proof in owner updates so users see savings without opening a dashboard.
+
 
 ## Trust and Data Boundaries
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmarrow/install",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Universal installer for Marrow passive agent setup.",
   "bin": {
     "marrow-install": "bin/marrow-install.js"
@@ -15,8 +15,6 @@
     "marrow",
     "mcp",
     "installer",
-    "governance",
-    "runner",
     "passive-runtime"
   ],
   "repository": {

package/src/installer.js

@@ -105,12 +105,6 @@ function findUp(startDir, names, maxDepth = 8) {
 }
 
 function projectRoot(startDir) {
-  const resolved = path.resolve(startDir);
-  if (path.basename(resolved) === '.marrow') return path.dirname(resolved);
-  if (path.basename(resolved) === 'env' && path.basename(path.dirname(resolved)) === '.marrow') {
-    return path.dirname(path.dirname(resolved));
-  }
-  if (exists(path.join(resolved, '.marrow'))) return resolved;
   const marker = findUp(startDir, ['package.json', 'pyproject.toml', 'requirements.txt', '.git', 'AGENTS.md', 'CLAUDE.md']);
   return marker ? path.dirname(marker) : path.resolve(startDir);
 }
@@ -289,7 +283,8 @@ Marrow should run passively after install:
 
 - Use MCP hooks when available: \`npx -y @getmarrow/mcp setup\`.
 - Use SDK passive runtime in owned Node processes: \`createPassiveRuntime().install()\`.
-- Before risky work, use Marrow's before-action intervention from \`GET /v1/agent/status\` or \`POST /v1/agent/runtime\`.
+- Keep passive token/model usage proof enabled so Marrow can show token, cost, latency, and workflow savings after real work completes.
+- Before risky work, use Marrow's decision brief or passive prompt hook.
 - After meaningful work, record the outcome so future agents learn from it.
 - Check health with \`marrow_agent_status\` or \`GET /v1/agent/status\`.
 
@@ -297,6 +292,7 @@ Required environment:
 
 - \`MARROW_API_KEY\`
 - Optional: \`MARROW_BASE_URL\`, \`MARROW_FLEET_AGENT_ID\`
+- Optional: \`MARROW_PASSIVE_TOKEN_USAGE=false\` disables compact provider usage capture when needed.
 ${MARROW_BLOCK_END}`;
 }
 
@@ -318,6 +314,7 @@ if (apiKey && !globalThis.__MARROW_PASSIVE_RUNTIME__) {
       useAgentRuntime: process.env.MARROW_AGENT_RUNTIME !== 'false',
       useWorkflowGate: process.env.MARROW_WORKFLOW_GATE !== 'false',
       requireOutcomeClosure: process.env.MARROW_REQUIRE_OUTCOME_CLOSURE !== 'false',
+      captureModelUsage: process.env.MARROW_PASSIVE_TOKEN_USAGE !== 'false',
     });
 
     runtime.install();
@@ -339,6 +336,7 @@ MARROW_PASSIVE_VALUE_REPORT=true
 MARROW_AGENT_RUNTIME=true
 MARROW_WORKFLOW_GATE=true
 MARROW_REQUIRE_OUTCOME_CLOSURE=true
+MARROW_PASSIVE_TOKEN_USAGE=true
 `;
 }
 
@@ -633,8 +631,14 @@ async function runSelfTest(options) {
     ok: false,
     error: error instanceof Error ? error.message : String(error),
   }));
-  const firstValueSignal = buildFirstValueSignal(status, runtime, performance, firstValue);
-  const installValueMoment = buildInstallValueMoment(firstValueSignal, status, runtime, performance, firstValue);
+  const valueProof = await requestJson(`${baseUrl}/v1/agent/value/proof?period_days=30`, { headers })
+    .catch((error) => ({
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    }));
+  const tokenValueProof = buildTokenValueProof(valueProof);
+  const firstValueSignal = buildFirstValueSignal(status, runtime, performance, firstValue, tokenValueProof);
+  const installValueMoment = buildInstallValueMoment(firstValueSignal, status, runtime, performance, firstValue, tokenValueProof);
   return {
     skipped: false,
     decision_id: decisionId,
@@ -646,11 +650,11 @@ async function runSelfTest(options) {
     auto_outcome_closure: status.auto_outcome_closure || null,
     runtime_active: Boolean(runtime && runtime.ok !== false),
     runtime_exact_next_action: runtime.exact_next_action || null,
-    runtime_before_you_act: runtime.intervention?.agent_copy || runtime.intervention?.before_action || runtime.before_you_act || null,
-    runtime_intervention: runtime.intervention || null,
+    runtime_before_you_act: runtime.before_you_act || null,
     first_value: firstValue && firstValue.ok !== false ? firstValue : null,
     first_value_signal: firstValueSignal,
     install_value_moment: installValueMoment,
+    token_value_proof: tokenValueProof,
     performance_proof: performance && performance.ok !== false ? {
       avoided_mistakes: performance.avoided_mistakes ?? performance.avoided_repeated_mistakes ?? 0,
       reused_winning_decisions: performance.reused_winning_decisions ?? 0,
@@ -662,11 +666,30 @@ async function runSelfTest(options) {
   };
 }
 
-function buildInstallValueMoment(firstValueSignal = {}, status = {}, runtime = {}, performance = {}, firstValue = {}) {
+function buildTokenValueProof(valueProof = {}) {
+  const modelUsage = valueProof && valueProof.ok !== false
+    ? valueProof.model_usage || valueProof.token_value_signal || valueProof
+    : null;
+  if (!modelUsage || typeof modelUsage !== 'object') {
+    return {
+      enabled: true,
+      capture_default: 'on_when_sdk_mcp_or_installer_hooks_available',
+      observed: { model_calls: 0, tokens: { total: 0 } },
+      savings: { estimated_tokens_saved: 0, estimated_minutes_saved: 0, confidence: 'none', method: 'warming_up' },
+      proof_line: 'Token usage capture is ready; no model calls have been reported yet.',
+      exact_next_action: 'Keep passive token capture enabled so Marrow can attach usage proof after real model calls complete.',
+    };
+  }
+  return modelUsage;
+}
+
+function buildInstallValueMoment(firstValueSignal = {}, status = {}, runtime = {}, performance = {}, firstValue = {}, tokenValueProof = null) {
   if (firstValue && firstValue.ok !== false && firstValue.first_value) {
+    const proof = Array.isArray(firstValue.first_value.proof) ? [...firstValue.first_value.proof] : [];
+    if (tokenValueProof?.proof_line && !proof.includes(tokenValueProof.proof_line)) proof.push(tokenValueProof.proof_line);
     return {
       headline: firstValue.headline || firstValue.first_value.headline || 'Your agent is no longer starting from zero.',
-      proof: Array.isArray(firstValue.first_value.proof) ? firstValue.first_value.proof : [],
+      proof,
       fleet_signal: firstValue.history_signal?.summary || 'Fresh account: Marrow will build fleet memory from this first captured outcome.',
       try_this_now: firstValue.first_value.try_this_now || 'Ask your agent: "I am about to deploy to production. What should I check first?"',
       expected_response: firstValue.first_value.expected_response || 'Marrow should answer with a risk gate, required proof, and any matching fleet lessons before the agent acts.',
@@ -676,9 +699,7 @@ function buildInstallValueMoment(firstValueSignal = {}, status = {}, runtime = {
 
   const proof = firstValueSignal.value_proof || [];
   const hasFleetSignal = proof.length > 0;
-  const runtimeLesson = runtime.intervention?.agent_copy
-    || runtime.intervention?.before_action
-    || runtime.before_you_act
+  const runtimeLesson = runtime.before_you_act
     || runtime.before_you_act_injection?.message
     || runtime.exact_next_action
     || firstValueSignal.first_lesson;
@@ -689,18 +710,19 @@ function buildInstallValueMoment(firstValueSignal = {}, status = {}, runtime = {
       'Captured this setup decision',
       'Closed the outcome successfully',
       'Runtime gate is ' + (firstValueSignal.active ? 'active' : 'installed'),
-      runtime.intervention?.must_use_before_action ? 'Before-action intervention is active for risky work' : runtimeLesson ? 'Future risky work now gets a pre-action brief' : 'Future risky work now gets checked before action',
+      runtimeLesson ? 'Future risky work now gets a pre-action brief' : 'Future risky work now gets checked before action',
+      tokenValueProof?.proof_line || 'Token usage proof is active and warming up after the first model call',
     ],
     fleet_signal: hasFleetSignal
       ? 'Marrow already found signal: ' + proof.join('; ') + '.'
       : 'Fresh account: Marrow will start building fleet memory from this first captured outcome.',
     try_this_now: 'Ask your agent: "I am about to deploy to production. What should I check first?"',
-    expected_response: 'Marrow should answer with proceed/warn/block, required proof, and any matching prior lesson/playbook before the agent acts.',
-    first_lesson: runtimeLesson || 'Marrow will stop agents before risky or repeated work and surface the prior lesson/playbook.',
+    expected_response: 'Marrow should answer with a risk gate, required proof, and any matching fleet lessons before the agent acts.',
+    first_lesson: runtimeLesson || 'Marrow will surface prior lessons before risky or repeated work.',
   };
 }
 
-function buildFirstValueSignal(status, runtime, performance, firstValue = {}) {
+function buildFirstValueSignal(status, runtime, performance, firstValue = {}, tokenValueProof = null) {
   if (firstValue && firstValue.ok !== false && firstValue.first_value) {
     const capture = firstValue.capture || {};
     const proof = firstValue.value_proof || {};
@@ -709,11 +731,13 @@ function buildFirstValueSignal(status, runtime, performance, firstValue = {}) {
     if (Number(proof.reused_winning_decisions || 0) > 0) proofBits.push(`${proof.reused_winning_decisions} reused winning decision(s)`);
     if (Number(proof.prevented_bad_actions || 0) > 0) proofBits.push(`${proof.prevented_bad_actions} prevented risky action(s)`);
     if (Number(proof.estimated_tokens_saved || 0) > 0) proofBits.push(`~${proof.estimated_tokens_saved} tokens saved`);
+    if (Number(tokenValueProof?.savings?.estimated_tokens_saved || 0) > 0) proofBits.push(`~${tokenValueProof.savings.estimated_tokens_saved} measured model tokens saved`);
+    else if (tokenValueProof?.proof_line) proofBits.push(tokenValueProof.proof_line);
     return {
       active: Boolean(firstValue.active),
       headline: `Marrow active: ${(capture.surfaces || ['decisions']).join(', ')} captured.`,
       captured: capture.surfaces || ['decisions'],
-      first_lesson: firstValue.first_value.first_lesson || runtime?.intervention?.agent_copy,
+      first_lesson: firstValue.first_value.first_lesson,
       value_proof: proofBits,
       next_action: firstValue.next_action?.reason || 'Keep working; Marrow will capture outcomes and reuse lessons automatically.',
     };
@@ -736,6 +760,8 @@ function buildFirstValueSignal(status, runtime, performance, firstValue = {}) {
   if (Number(proof.prevented_bad_actions || 0) > 0) proofBits.push(`${proof.prevented_bad_actions} prevented risky action(s)`);
   const tokens = proof.token_time_saved_estimate?.estimated_tokens_saved || 0;
   if (tokens > 0) proofBits.push(`~${tokens} tokens saved`);
+  if (Number(tokenValueProof?.savings?.estimated_tokens_saved || 0) > 0) proofBits.push(`~${tokenValueProof.savings.estimated_tokens_saved} measured model tokens saved`);
+  else if (tokenValueProof?.proof_line) proofBits.push(tokenValueProof.proof_line);
 
   const firstLesson = runtime.before_you_act
     || runtime.before_you_act_injection?.message
@@ -799,6 +825,20 @@ function printReport(report) {
         process.stdout.write(`- Next: ${report.selfTest.first_value_signal.next_action}\n`);
       }
     }
+    if (report.selfTest.token_value_proof) {
+      const proof = report.selfTest.token_value_proof;
+      const observed = proof.observed || {};
+      const savings = proof.savings || {};
+      const tokens = observed.tokens || {};
+      process.stdout.write('\nToken value proof:\n');
+      process.stdout.write(`- passive capture: ${proof.enabled ? 'on' : 'unknown'}\n`);
+      process.stdout.write(`- model calls observed: ${observed.model_calls || 0}\n`);
+      process.stdout.write(`- tokens observed: ${tokens.total || 0}\n`);
+      process.stdout.write(`- estimated tokens saved: ${savings.estimated_tokens_saved || 0}\n`);
+      if (savings.confidence) process.stdout.write(`- confidence: ${savings.confidence}\n`);
+      if (proof.proof_line) process.stdout.write(`- proof: ${proof.proof_line}\n`);
+      if (proof.exact_next_action) process.stdout.write(`- next: ${proof.exact_next_action}\n`);
+    }
   }
 
   if (report.remediation) {
@@ -949,4 +989,5 @@ module.exports = {
   inspectNpmTokenConfig,
   inspectSdkDependency,
   buildInstallValueMoment,
+  buildTokenValueProof,
 };