@getmarrow/install 0.1.51 → 0.1.53

package/README.md

@@ -53,7 +53,7 @@ Verify current claims through the [public evidence manifest](https://getmarrow.a
 ## Install
 
 ```bash
-npx @getmarrow/install activate
+npx @getmarrow/install
 ```
 
 Required secret:
@@ -62,6 +62,8 @@ Required secret:
 export MARROW_API_KEY=mrw_live_...
 ```
 
+The bare command is the default-on path: it detects and byte-idempotently writes managed configuration, runs the authenticated activation self-test, and starts the supported persistent controller. The key stays process-only and is never written to generated configuration or controller state. Use `--dry-run` for a non-writing preview, `doctor` for a read-only health check, or `--no-controller` to install and self-test without starting the controller. The explicit `activate` command remains equivalent and supported.
+
 ## Keeping Marrow Current
 
 Marrow's hosted API, website, and dashboard update automatically; local SDK dependencies, generated runtime files, MCP hooks/configuration, and pinned package versions do not silently rewrite themselves. Keeping them current delivers new client-side features, compatibility improvements, and any published security fixes. Supported clients report their package version during authenticated status/runtime activity, and Marrow returns a `client_update` notice with the exact action when the version is behind or unknown.
@@ -91,9 +93,15 @@ npx @getmarrow/install controller stop
 
 Persistent controller lifecycle is currently Linux-only. On macOS or Windows, activation still writes supported configuration and verifies one server-side install self-test without certifying that hooks continuously ran; run `npx @getmarrow/install sidecar` under an owner-managed service and pass `--no-controller`. The controller does not silently upgrade packages, change governance policy, rotate credentials, or modify unrelated project configuration.
 
-## What's New in v0.1.51
+## What's New in v0.1.53
+
+v0.1.53 pins the native-gate MCP candidate `3.9.75` and reconciles only Marrow-owned native hook surfaces. Codex uses `.codex/hooks.json`; Cursor and Composer use `.cursor/hooks.json`; Cline uses bounded executables under `.clinerules/hooks/`; Windsurf uses `.windsurf/hooks.json`; Gemini CLI receives named BeforeTool, AfterTool, and AfterAgent groups in `.gemini/settings.json`; Grok receives trusted global hooks in `~/.grok/hooks/marrow.json`. Grok PreToolUse validates strict private allow/deny JSON and fails closed with exit `2` when the child cannot provide an exact decision; PostToolUse/PostToolUseFailure emit compact results; one nonblocking Stop hook closes the turn with no duplicate SessionEnd hook. Grok hooks remain user-toggleable, so restart plus `/hooks` inspection is required and configuration never proves observed coverage.
+
+The integration boundary is explicit: native hooks remain cooperative/client-reported until authoritative server receipts exist; MCP tools are on demand; Codex requires restart plus owner `/hooks` trust review; Windsurf requires restart, workspace trust review, and Restricted Mode to be off; Gemini CLI requires restart and `/hooks panel` fingerprint review/approval, with `/hooks enable-all` reserved for an explicitly disabled configuration after owner review; Grok requires restart and `/hooks` inspection because its trusted global hooks remain user-toggleable; the governed wrapper remains an explicit bounded fallback; owned Node processes use the SDK passive runtime while installed; and custom hosts require a bounded event adapter. Exact package SHA/integrity can prove artifact provenance, not runtime coverage.
+
+## Previous: v0.1.52
 
-v0.1.51 keeps MCP `3.9.74` and SDK `3.7.62`, and makes generated passive runtime identity follow the current process: `MARROW_FLEET_AGENT_ID` first, then `MARROW_AGENT_ID`, with the installer-captured identity retained only as a fallback. This prevents a stale installed harness identity from overriding the current Codex, Bob, or other canonical process identity. Managed MCP config does not store an API key or shell-style credential placeholder; the owning harness inherits the key from trusted environment or secret-manager state.
+v0.1.52 keeps MCP `3.9.74` and SDK `3.7.62`, and makes generated passive runtime identity follow the current process: `MARROW_FLEET_AGENT_ID` first, then `MARROW_AGENT_ID`, with the installer-captured identity retained only as a fallback. This prevents a stale installed harness identity from overriding the current Codex, Bob, or other canonical process identity. Managed MCP config does not store an API key or shell-style credential placeholder; the owning harness inherits the key from trusted environment or secret-manager state.
 
 The integration boundary is explicit: native Claude hooks are installed only where supported and remain cooperative/client-reported until authoritative server receipts exist; MCP tools are on demand; Codex, Grok, Gemini, and similar CLIs use the governed wrapper for consequential control; owned Node processes use the SDK passive runtime while installed; and custom hosts require a bounded event adapter. Exact package SHA/integrity can prove artifact provenance, not runtime coverage. Activation-profile delivery is authenticated `client_self_reported` telemetry with `certified_coverage: false`; it acknowledges delivery but cannot attest that a hook, wrapper, or adapter ran.
 
@@ -116,7 +124,7 @@ v0.1.47 makes activate honest about reload and the first capture path:
 v0.1.46 makes default install cover every workspace honestly:
 
 - auto mode now writes MCP plus agent instructions in every project, and the SDK passive runtime whenever Node is present;
-- Claude native hooks still install only when `.claude` is present; detected Cursor workspaces also get `.cursor/mcp.json`;
+- Claude native hooks still install only when `.claude` is present; detected Cursor workspaces get `.cursor/hooks.json` plus `.cursor/mcp.json`, and Composer uses that same Cursor-native lifecycle path;
 - Hermes, OpenClaw, and custom hosts stay event-contract only and are not claimed as native interception;
 - generated MCP setup, launch, and certified hook commands pin current MCP `3.9.64` from source `ed8293165247e89161045c7fbf68aeee4d51c6da`;
 - SDK detection and operator-approved upgrade rules pin exact public `3.7.59`;
@@ -352,8 +360,11 @@ Run `npx @getmarrow/install integrations --json` for the machine-readable matrix
 | Harnesses | Prompt / pre-action / result | Closure and proof | Cached brief | Restart survival | Evidence adapter | Safe repair |
 | --- | --- | --- | --- | --- | --- | --- |
 | Claude Code | Configured native hooks where supported; cooperative/client-reported until authoritative receipts exist | Correlated when determinable; proof is evaluated and is advisory or enforced according to plan policy | Owner-only bounded cache | Installed config and durable spool | Native hook evidence | Managed config after activation |
-| Cursor, Composer, Cline, Windsurf | MCP-routed only | MCP-routed; explicit or governed proof | Owner-only MCP cache | MCP config and durable spool | MCP lifecycle evidence | Managed config after activation |
-| Codex, OpenCode, Gemini, Grok, DeepSeek, Qwen, Kimi, MiniMax, GLM | Automatic only inside governed runner | Automatic when result is known; proof is evaluated and is advisory or enforced according to plan policy | Runner/runtime cache | Activated controller and durable buffer | Command, test, deployment, or owner evidence | Managed config after activation |
+| Cursor, Composer | Native hooks plus MCP on demand | Native pre-action/result/closeout; explicit proof | Owner-only MCP cache | Hook/MCP config and durable spool | Client-self-reported lifecycle evidence | Managed config after activation and trust review |
+| Cline | Native PreToolUse/PostToolUse/TaskCancel plus MCP on demand | Native pre-action/result/cancel closeout; TaskComplete unverified | Owner-only MCP cache | Non-overwriting executable hooks and durable spool | Client-self-reported lifecycle evidence | Enable Hooks, executable/workspace trust, and restart required |
+| Windsurf | MCP-routed only | MCP-routed; explicit or governed proof | Owner-only MCP cache | MCP config and durable spool | MCP lifecycle evidence | Managed config after activation |
+| Codex, Gemini, Grok | Native hooks plus MCP on demand | Native pre-action/result/turn closeout; Grok Stop never blocks or retries | Owner-only MCP cache | Hook/MCP config and durable spool | Client-self-reported lifecycle evidence | Restart and host hook review required |
+| OpenCode, DeepSeek, Qwen, Kimi, MiniMax, GLM | Automatic only inside governed runner | Automatic when result is known; proof is evaluated and is advisory or enforced according to plan policy | Runner/runtime cache | Activated controller and durable buffer | Command, test, deployment, or owner evidence | Managed config after activation |
 | Hermes, OpenClaw, custom harnesses | Lifecycle adapter required | Adapter or governed runner required | Adapter dependent | Adapter dependent | Adapter supplied | Adapter owned |
 
 For native hooks, a successful tool exit is not treated as a successful business outcome when proof is missing. MCP coverage includes only actions routed through that MCP client. Governed-runner coverage includes only commands launched through the runner. Event-contract integrations must emit the documented lifecycle themselves.

package/bin/marrow-install.js

@@ -2,10 +2,11 @@
 
 const installer = require('../src/installer');
 const governedRunner = require('../src/governed-runner');
+const { runControlCli } = require('../src/control-state');
 
 const argv = process.argv.slice(2);
 const governedCommands = new Set(['run', 'gate', 'proof', 'status', 'govern', 'fleet', 'hermes', 'openclaw', 'integrations', 'permit', 'verify-permit', 'coverage', 'sidecar', 'controller']);
-const runCli = governedCommands.has(argv[0]) ? governedRunner.runCli : installer.runCli;
+const runCli = argv[0] === 'control' ? runControlCli : governedCommands.has(argv[0]) ? governedRunner.runCli : installer.runCli;
 
 runCli(argv).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmarrow/install",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "Universal installer and governed runner for Marrow agent fleets.",
   "bin": {
     "marrow-install": "bin/marrow-install.js"

package/src/control-state.js

@@ -0,0 +1,116 @@
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const CONTROL_STATE_VERSION = 1;
+const CONTROL_STATE_DIRECTORY = '.marrow';
+const CONTROL_STATE_FILENAME = 'control.json';
+const CONTROL_CHANGED_BY = 'owner_cli';
+const CONTROL_MAX_BYTES = 4096;
+const CONTROL_BYPASS_ACTION = 'protected action bypassed while local control disabled';
+const CONTROL_BYPASS_LEDGER_FILENAME = 'control-bypass-receipts.json';
+
+class UnsafeControlStateError extends Error {
+  constructor() { super('Local Marrow control state is unsafe or invalid. Protected actions remain blocked; inspect ~/.marrow/control.json and run npx @getmarrow/install control status.'); this.name = 'UnsafeControlStateError'; }
+}
+
+function statePaths(home = os.homedir()) {
+  const directory = path.join(home, CONTROL_STATE_DIRECTORY);
+  return { directory, target: path.join(directory, CONTROL_STATE_FILENAME) };
+}
+function unsafe() { throw new UnsafeControlStateError(); }
+function ownedPrivate(stat, mode) {
+  return !stat.isSymbolicLink() && stat.uid === (typeof process.getuid === 'function' ? process.getuid() : stat.uid) && (stat.mode & 0o777) === mode;
+}
+function readLocalControlState(options = {}) {
+  const { directory, target } = statePaths(options.home);
+  let ds;
+  try { ds = fs.lstatSync(directory); } catch (error) { if (error.code === 'ENOENT') return { enabled: true, state: 'default_enabled', changed_at: null }; return unsafe(); }
+  if (!ds.isDirectory() || ds.isSymbolicLink()) return unsafe();
+  let ts;
+  try { ts = fs.lstatSync(target); } catch (error) { if (error.code === 'ENOENT') return { enabled: true, state: 'default_enabled', changed_at: null }; return unsafe(); }
+  if (!ownedPrivate(ds, 0o700)) return unsafe();
+  if (!ts.isFile() || !ownedPrivate(ts, 0o600) || ts.size < 2 || ts.size > CONTROL_MAX_BYTES) return unsafe();
+  let fd = -1;
+  try {
+    fd = fs.openSync(target, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const opened = fs.fstatSync(fd);
+    if (!opened.isFile() || opened.ino !== ts.ino || !ownedPrivate(opened, 0o600)) return unsafe();
+    const raw = fs.readFileSync(fd, 'utf8');
+    if (Buffer.byteLength(raw) > CONTROL_MAX_BYTES) return unsafe();
+    const value = JSON.parse(raw);
+    if (!value || Array.isArray(value) || Object.keys(value).sort().join(',') !== 'change_id,changed_at,changed_by,enabled,version') return unsafe();
+    const changedAt = typeof value.changed_at === 'string' ? value.changed_at : '';
+    const valid = value.version === CONTROL_STATE_VERSION && typeof value.enabled === 'boolean' && value.changed_by === CONTROL_CHANGED_BY
+      && changedAt && new Date(changedAt).toISOString() === changedAt && typeof value.change_id === 'string' && /^ctl_[a-f0-9]{32}$/.test(value.change_id);
+    if (!valid) return unsafe();
+    return { enabled: value.enabled, state: value.enabled ? 'enabled' : 'disabled', changed_at: changedAt, change_id: value.change_id };
+  } catch (error) { if (error instanceof UnsafeControlStateError) throw error; return unsafe(); }
+  finally { if (fd >= 0) fs.closeSync(fd); }
+}
+function writeLocalControlState(enabled, options = {}) {
+  const current = readLocalControlState(options);
+  if (current.enabled === enabled) return { ...current, changed: false, receipt: null };
+  const { directory, target } = statePaths(options.home);
+  if (!fs.existsSync(directory)) fs.mkdirSync(directory, { mode: 0o700 });
+  const ds = fs.lstatSync(directory);
+  if (!ds.isDirectory() || !ownedPrivate(ds, 0o700)) return unsafe();
+  const value = { version: CONTROL_STATE_VERSION, enabled, changed_at: new Date().toISOString(), change_id: `ctl_${crypto.randomBytes(16).toString('hex')}`, changed_by: CONTROL_CHANGED_BY };
+  const bytes = `${JSON.stringify(value)}\n`;
+  const temp = path.join(directory, `.control.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`);
+  let fd = -1;
+  try {
+    fd = fs.openSync(temp, 'wx', 0o600); fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); fs.closeSync(fd); fd = -1;
+    fs.renameSync(temp, target);
+    const dirFd = fs.openSync(directory, 'r'); try { fs.fsyncSync(dirFd); } finally { fs.closeSync(dirFd); }
+  } finally { if (fd >= 0) fs.closeSync(fd); try { fs.unlinkSync(temp); } catch {} }
+  return { enabled, state: enabled ? 'enabled' : 'disabled', changed_at: value.changed_at, change_id: value.change_id, changed: true, receipt: { action: enabled ? 'local control enabled' : 'local control disabled', change_id: value.change_id, changed_at: value.changed_at } };
+}
+function evidence(options = {}) {
+  try { const s = readLocalControlState(options); return { ...s, bypass_recording_available: Boolean(options.apiKey), exact_next_action: s.enabled ? 'Run npx @getmarrow/install control disable --yes to disable local enforcement.' : 'Run npx @getmarrow/install control enable to resume local enforcement; hooks poll local state without reinstalling.' }; }
+  catch { return { enabled: false, state: 'error', changed_at: null, bypass_recording_available: false, exact_next_action: 'Inspect and replace unsafe ~/.marrow/control.json, then run npx @getmarrow/install control status; protected actions remain blocked.' }; }
+}
+async function bestEffortLifecycle(event, options = {}) {
+  const key = options.apiKey || process.env.MARROW_API_KEY || process.env.MARROW_KEY;
+  if (!key || typeof fetch !== 'function') return false;
+  try { const response = await fetch(`${String(options.baseUrl || process.env.MARROW_BASE_URL || 'https://api.getmarrow.ai').replace(/\/$/, '')}/v1/agent/integrations/events`, { method: 'POST', headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' }, body: JSON.stringify(event), signal: AbortSignal.timeout(1500) }); return response.ok; } catch { return false; }
+}
+function boundedIdentity(value, fallback) { const safe = String(value || '').trim().replace(/[^A-Za-z0-9._-]/g, '-').slice(0, 64); return safe || fallback; }
+function persistBypassReceipt(input, options = {}) {
+  const { directory } = statePaths(options.home);
+  if (!fs.existsSync(directory)) fs.mkdirSync(directory, { mode: 0o700 });
+  const ds = fs.lstatSync(directory); if (!ds.isDirectory() || !ownedPrivate(ds, 0o700)) return unsafe();
+  const target = path.join(directory, CONTROL_BYPASS_LEDGER_FILENAME);
+  let receipts = [];
+  if (fs.existsSync(target)) {
+    const ts = fs.lstatSync(target); if (!ts.isFile() || !ownedPrivate(ts, 0o600) || ts.size > CONTROL_MAX_BYTES * 8) return unsafe();
+    receipts = JSON.parse(fs.readFileSync(target, 'utf8')); if (!Array.isArray(receipts)) return unsafe();
+  }
+  const receipt = { version: 1, action: CONTROL_BYPASS_ACTION, harness: boundedIdentity(input.harness, 'governed_runner'), agent_id: boundedIdentity(input.agentId, 'local-owner'), surfaces: [...new Set((input.surfaces || []).filter((v) => ['production','github','npm','secrets','database','financial','filesystem'].includes(v)))].slice(0, 6), risk_level: input.risk === 'high' ? 'high' : 'medium', correlation_id: `bypass_${crypto.randomBytes(16).toString('hex')}`, source: 'client_self_reported', intervention_disposition: 'overridden', action_changed: false, recorded_at: new Date().toISOString() };
+  receipts = [...receipts.slice(-63), receipt]; const bytes = `${JSON.stringify(receipts)}\n`; if (Buffer.byteLength(bytes) > CONTROL_MAX_BYTES * 8) return unsafe();
+  const temp = path.join(directory, `.bypass.${process.pid}.${crypto.randomBytes(8).toString('hex')}.tmp`); let fd = -1;
+  try { fd = fs.openSync(temp, 'wx', 0o600); fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); fs.closeSync(fd); fd = -1; fs.renameSync(temp, target); }
+  finally { if (fd >= 0) fs.closeSync(fd); try { fs.unlinkSync(temp); } catch {} }
+  return receipt;
+}
+async function recordGovernedBypass(input, options = {}) {
+  const receipt = persistBypassReceipt(input, options);
+  const remote_delivered = await bestEffortLifecycle({ event_type: 'pre_action_checked', ...receipt }, options);
+  return { bypass_recorded: true, remote_delivered, receipt };
+}
+async function runControlCli(argv, options = {}) {
+  const action = argv[1] || 'status'; const json = argv.includes('--json');
+  if (!['status', 'disable', 'enable'].includes(action)) throw new Error('control action must be status, disable, or enable');
+  if (action === 'disable' && !argv.includes('--yes')) throw new Error('control disable requires --yes owner confirmation; no state was changed');
+  let result = action === 'status' ? evidence(options) : writeLocalControlState(action === 'enable', options);
+  if (result.changed) {
+    const delivered = await bestEffortLifecycle({ event_type: 'journey_update', action: result.receipt.action, source: 'client_self_reported', harness: 'installer', agent_id: boundedIdentity(options.agentId || process.env.MARROW_FLEET_AGENT_ID || process.env.MARROW_AGENT_ID, 'local-owner'), correlation_id: result.change_id }, options);
+    result = { ...result, lifecycle_delivered: delivered };
+  }
+  if (json) process.stdout.write(`${JSON.stringify({ ok: result.state !== 'error', local_control: result }, null, 2)}\n`);
+  else process.stdout.write(`Marrow local control: ${result.state}. ${result.exact_next_action || ''}\n`);
+  return result;
+}
+
+module.exports = { CONTROL_STATE_VERSION, CONTROL_STATE_DIRECTORY, CONTROL_STATE_FILENAME, CONTROL_CHANGED_BY, CONTROL_MAX_BYTES, CONTROL_BYPASS_ACTION, CONTROL_BYPASS_LEDGER_FILENAME, UnsafeControlStateError, readLocalControlState, writeLocalControlState, evidence, bestEffortLifecycle, persistBypassReceipt, recordGovernedBypass, runControlCli };

package/src/first-hour.js

@@ -16,13 +16,37 @@ function harnessReloadPlan(detection = {}, changes = []) {
   if (detection.cursor) {
     clients.push({
       client: 'cursor',
-      restart: 'Restart Cursor so project MCP loads.',
+      restart: 'Restart Cursor or Composer, then review the trusted workspace hooks with /hooks so native lifecycle hooks and project MCP load.',
+    });
+  }
+  if (detection.cline) {
+    clients.push({
+      client: 'cline',
+      restart: 'Enable Hooks in Cline, trust the project hook executables and workspace, then restart Cline. TaskComplete remains unverified.',
+    });
+  }
+  if (detection.windsurf) {
+    clients.push({
+      client: 'windsurf',
+      restart: 'Restart Windsurf, trust the workspace hook configuration, and leave Restricted Mode so native hooks can run.',
+    });
+  }
+  if (detection.gemini) {
+    clients.push({
+      client: 'gemini',
+      restart: 'Restart Gemini CLI, open /hooks panel, and review and approve the project hook fingerprints before treating native hooks as live.',
+    });
+  }
+  if (detection.grok) {
+    clients.push({
+      client: 'grok',
+      restart: 'Restart Grok, inspect /hooks, and confirm the trusted global Marrow hooks are enabled before treating them as live.',
     });
   }
   if (detection.codex) {
     clients.push({
       client: 'codex',
-      restart: 'Start a new Codex or Grok session so AGENTS.md and MCP config load.',
+      restart: 'Start a new Codex session, then review the repository hooks with /hooks before treating them as trusted or live.',
     });
   }
   if (clients.length === 0) {
@@ -54,16 +78,56 @@ function firstCapturePath(detection = {}, agentId) {
   if (detection.cursor) {
     return {
       client: 'cursor',
-      capability_level: 'mcp',
-      command: 'marrow_agent_runtime',
-      instruction: 'After restart, call marrow_agent_runtime before the next deploy, merge, or publish. Before the session ends, call marrow_session_end. Cursor MCP tools are on demand.',
+      capability_level: 'native_hooks',
+      command: null,
+      instruction: 'After restart and trusted-workspace /hooks review, Cursor and Composer use the same native pre-action, action-result, and outcome-closeout hooks. MCP tools remain on demand. Configuration does not verify runtime coverage.',
+    };
+  }
+  if (detection.cline) {
+    return {
+      client: 'cline',
+      capability_level: 'native_hooks',
+      command: null,
+      instruction: 'After Enable Hooks, executable/workspace trust, and restart, Cline uses native PreToolUse, PostToolUse, and TaskCancel hooks. MCP remains on demand. TaskComplete is documented as coming soon and is not verified coverage; configuration does not prove passive runtime coverage.',
+    };
+  }
+  if (detection.windsurf) {
+    return {
+      client: 'windsurf',
+      capability_level: 'native_hooks',
+      command: null,
+      instruction: 'After restart, workspace trust review, and leaving Restricted Mode, Windsurf uses native pre-action, success-result, and response-closeout hooks. MCP tools remain on demand. Configuration does not verify runtime coverage.',
+    };
+  }
+  if (detection.gemini) {
+    return {
+      client: 'gemini',
+      capability_level: 'native_hooks',
+      command: null,
+      instruction: 'After restart and project fingerprint review and approval in /hooks panel, Gemini CLI uses native BeforeTool, AfterTool, and AfterAgent hooks. MCP tools remain on demand. Explicit hook disablement is preserved, and configuration does not verify runtime coverage.',
+    };
+  }
+  if (detection.codex) {
+    return {
+      client: 'codex',
+      capability_level: 'native_hooks',
+      command: null,
+      instruction: 'After restart and owner /hooks trust review, Codex native hooks capture prompt, pre-action, action-result, and session-end events. Configuration alone does not verify runtime coverage.',
+    };
+  }
+  if (detection.grok) {
+    return {
+      client: 'grok',
+      capability_level: 'native_hooks',
+      command: null,
+      instruction: 'After restart and /hooks inspection, Grok uses global native pre-action, result, failure-result, and one nonblocking Stop closeout hook. Hooks remain user-toggleable, MCP tools stay on demand, and configuration does not verify observed runtime coverage. The governed runner remains an explicit bounded fallback.',
     };
   }
   return {
-    client: detection.codex ? 'codex' : 'governed_wrapper',
+    client: 'governed_wrapper',
     capability_level: 'governed_wrapper',
     command: `npx @getmarrow/install run --agent ${id} -- -- <command>`,
-    instruction: 'Wrap the next deploy, merge, or publish with the governed runner. Codex and Grok do not intercept tools natively. Before the session ends, call marrow_session_end or marrow_commit. Do not invent token counts.',
+    instruction: 'Wrap the next deploy, merge, or publish with the governed runner for hosts without a native gate. Before the session ends, call marrow_session_end or marrow_commit. Do not invent token counts.',
   };
 }
 

package/src/governed-runner.js

@@ -27,6 +27,8 @@ const {
   buildPlan,
   detectEnvironment,
 } = require('./installer');
+const { createHostUsageCapture } = require('./usage-telemetry');
+const { readLocalControlState, recordGovernedBypass } = require('./control-state');
 
 const DEFAULT_BASE_URL = 'https://api.getmarrow.ai';
 const MCP_SETUP_COMMAND = `npx -y --package=${ADAPTER_PROVENANCE.mcp.package}@${ADAPTER_PROVENANCE.mcp.version} marrow-mcp setup`;
@@ -512,11 +514,11 @@ function dataOf(json) {
   return json && typeof json === 'object' && json.data && typeof json.data === 'object' ? json.data : json;
 }
 
-async function requestJson(options, method, route, body) {
+async function requestJson(options, method, route, body, extraHeaders = {}) {
   if (!options.apiKey) throw new Error('MARROW_API_KEY is required. Use --fail-open only for non-production local commands.');
   const response = await fetch(new URL(route, options.baseUrl.replace(/\/$/, '/')), {
     method,
-    headers: headers(options),
+    headers: { ...headers(options), ...extraHeaders },
     body: body === undefined ? undefined : JSON.stringify(body),
   });
   const text = await response.text();
@@ -674,15 +676,48 @@ function printGate(decision, runtime, stream = process.stdout) {
   if (runtime?.value_proof?.owner_summary) stream.write(`Value: ${runtime.value_proof.owner_summary}\n`);
 }
 
-function runChild(command, env = process.env) {
+function runChild(command, env = process.env, stdout = process.stdout) {
   return new Promise((resolve) => {
+    const usageCapture = createHostUsageCapture(command);
     const child = spawn(command[0], command.slice(1), {
-      stdio: 'inherit',
+      stdio: usageCapture.supported ? ['inherit', 'pipe', 'inherit'] : 'inherit',
       shell: false,
       env,
     });
-    child.on('error', (error) => resolve({ exitCode: 127, error }));
-    child.on('close', (code, signal) => resolve({ exitCode: code ?? 1, signal: signal || null }));
+    let closed = null;
+    let pendingWrites = 0;
+    let settled = false;
+    const settle = () => {
+      if (settled || !closed || pendingWrites > 0) return;
+      settled = true;
+      resolve({
+        ...closed,
+        usageCaptureSupported: usageCapture.supported,
+        modelUsage: usageCapture.finish(),
+      });
+    };
+    if (usageCapture.supported && child.stdout) {
+      child.stdout.on('data', (chunk) => {
+        usageCapture.write(chunk);
+        pendingWrites += 1;
+        const ready = stdout.write(chunk, () => {
+          pendingWrites -= 1;
+          settle();
+        });
+        if (!ready) {
+          child.stdout.pause();
+          stdout.once('drain', () => child.stdout?.resume());
+        }
+      });
+    }
+    child.on('error', (error) => {
+      closed = { exitCode: 127, error };
+      settle();
+    });
+    child.on('close', (code, signal) => {
+      closed = { exitCode: code ?? 1, signal: signal || null };
+      settle();
+    });
   });
 }
 
@@ -718,7 +753,7 @@ async function createDecision(options, action, type, target, surfaces) {
   });
 }
 
-async function commitOutcome(options, decisionId, success, outcome, proof, gateReceiptId) {
+async function commitOutcome(options, decisionId, success, outcome, proof, gateReceiptId, modelUsage = null) {
   const body = {
     decision_id: decisionId,
     success,
@@ -727,10 +762,16 @@ async function commitOutcome(options, decisionId, success, outcome, proof, gateR
     source_meta: sourceMeta(options, 'commit', { action: outcome }),
   };
   if (gateReceiptId) body.gate_receipt_id = gateReceiptId;
-  return requestJson(options, 'POST', '/v1/agent/commit', body);
+  if (modelUsage) body.model_usage = modelUsage;
+  const commitHeaders = modelUsage
+    ? { 'Idempotency-Key': `marrow-run-${crypto.createHash('sha256')
+      .update(`${options.agentId}\u0000${options.sessionId}\u0000${decisionId}`)
+      .digest('hex')}` }
+    : {};
+  return requestJson(options, 'POST', '/v1/agent/commit', body, commitHeaders);
 }
 
-async function runGoverned(parsed) {
+async function runGoverned(parsed, execution = {}) {
   const { options, childCommand } = parsed;
   const commandText = redactedCommand(childCommand);
   const action = options.action ? redact(options.action) : commandText;
@@ -746,6 +787,18 @@ async function runGoverned(parsed) {
   let protectedAction = risky;
   const surfaces = inferSurfaces(commandText || action);
 
+  let localControl;
+  try { localControl = readLocalControlState(execution.controlStateOptions || {}); }
+  catch (error) {
+    if (protectedAction) return { ok: false, blocked: true, exitCode: 13, action, type, risky, message: error.message };
+    localControl = { enabled: true, state: 'error' };
+  }
+  if (!localControl.enabled) {
+    const bypass = protectedAction ? await recordGovernedBypass({ harness: options.client, agentId: options.agentId, surfaces, risk: risky ? 'high' : 'medium' }, { ...options, ...(execution.controlStateOptions || {}) }) : { bypass_recorded: false, remote_delivered: false };
+    const child = await runChild(childCommand, scopedExecutionEnv(null), execution.stdout || process.stdout);
+    return { ok: child.exitCode === 0, blocked: false, exitCode: child.exitCode, action, type, risky, local_control: 'owner_disabled', bypass_recorded: bypass.bypass_recorded, bypass_remote_delivered: bypass.remote_delivered, decision: null, decision_id: '', permit_id: null, permit_verified: false, permit_closed: false };
+  }
+
   try {
     runtime = await preflightRuntime(options, action, type, commandText);
     decision = gateDecision(runtime);
@@ -816,7 +869,7 @@ async function runGoverned(parsed) {
   }
 
   const childEnv = scopedExecutionEnv(permitVerified ? actionPermit : null);
-  const child = await runChild(childCommand, childEnv);
+  const child = await runChild(childCommand, childEnv, execution.stdout || process.stdout);
   const success = child.exitCode === 0;
   const proof = defaultProof({ options, action, childCommand, exitCode: child.exitCode, success });
   const outcome = success
@@ -826,7 +879,15 @@ async function runGoverned(parsed) {
   let commit = null;
   if (decisionId) {
     try {
-      commit = await commitOutcome(options, decisionId, success, outcome, proof, decision?.receiptId || '');
+      commit = await commitOutcome(
+        options,
+        decisionId,
+        success,
+        outcome,
+        proof,
+        decision?.receiptId || '',
+        child.modelUsage,
+      );
     } catch (error) {
       process.stderr.write(`Marrow outcome commit failed: ${error.message}\n`);
     }
@@ -861,6 +922,16 @@ async function runGoverned(parsed) {
     permit_id: actionPermit?.permit_id || null,
     permit_verified: permitVerified,
     permit_closed: Boolean(permitClosed),
+    usage_capture: {
+      supported: child.usageCaptureSupported === true,
+      observed: Boolean(child.modelUsage),
+      source: child.modelUsage?.source || null,
+      evidence: child.modelUsage
+        ? 'accepted_host_reported_usage'
+        : child.usageCaptureSupported
+        ? 'no_valid_host_reported_usage'
+        : 'unsupported_child_command',
+    },
   };
 }
 
@@ -964,6 +1035,16 @@ async function gateOnly(parsed) {
   const { options } = parsed;
   const action = redact(options.action);
   const type = options.type || inferType(action);
+  const protectedAction = isRisky(action, type);
+  let localControl;
+  try { localControl = readLocalControlState(); } catch (error) {
+    if (protectedAction) return { ok: false, allowed: false, blocked: true, exitCode: 13, action, type, decision: null, message: error.message };
+    localControl = { enabled: true };
+  }
+  if (!localControl.enabled) {
+    const bypass = protectedAction ? await recordGovernedBypass({ harness: options.client, agentId: options.agentId, surfaces: inferSurfaces(action), risk: 'high' }, options) : { bypass_recorded: false, remote_delivered: false };
+    return { ok: true, allowed: true, state: 'owner_disabled', action, type, bypass_recorded: bypass.bypass_recorded, bypass_remote_delivered: bypass.remote_delivered, decision: null, permit: null };
+  }
   const runtime = await preflightRuntime(options, action, type, action);
   const decision = gateDecision(runtime);
   printGate(decision, runtime);