@getmarrow/install 0.1.11 → 0.1.13

package/README.md

@@ -11,6 +11,72 @@ npx @getmarrow/install --repair
 npx @getmarrow/install doctor
 ```
 
+## 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`.
+
+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.
+
+- `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.
+- Risky actions can fail closed by default when Marrow requires owner approval, blocks an action, or requires missing proof.
+- Successful and failed commands automatically close outcomes through `/v1/agent/commit` with a redacted proof pack.
+- The runner sends action and command metadata only; it does not upload command stdout, stderr, full environment values, or plaintext API keys.
+- This gives teams a thin governance path for Codex, Claude Code, OpenClaw, OpenCode, Cursor, CI scripts, and custom shell-based agents.
+
+Business value: Marrow can sit in front of the commands that matter most, tell the agent what prior lesson or proof is required before action, and produce an audit-ready outcome trail after the command finishes.
+
+### Governed Runner Quickstart
+
+Preview the detected harnesses and protected command examples:
+
+```bash
+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
+MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run --agent codex-prod --profile production -- node -e "process.exit(0)"
+```
+
+Gate a production action before the agent executes it:
+
+```bash
+MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install gate "deploy production worker after tests pass"
+```
+
+Wrap a real deploy, publish, merge, or migration command only after the agent has the required proof:
+
+```bash
+MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run \
+  --agent deploy-agent \
+  --type deploy \
+  --profile production \
+  --policy enforce \
+  -- wrangler deploy
+```
+
+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.

package/bin/marrow-install.js

@@ -1,8 +1,13 @@
 #!/usr/bin/env node
 
-const { runCli } = require('../src/installer');
+const installer = require('../src/installer');
+const governedRunner = require('../src/governed-runner');
 
-runCli(process.argv.slice(2)).catch((error) => {
+const argv = process.argv.slice(2);
+const governedCommands = new Set(['run', 'gate', 'proof', 'status', 'govern']);
+const runCli = governedCommands.has(argv[0]) ? governedRunner.runCli : installer.runCli;
+
+runCli(argv).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   process.stderr.write(`marrow-install failed: ${message}\n`);
   process.exit(1);

package/package.json

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

package/src/governed-runner.js

@@ -0,0 +1,863 @@
+const { spawn } = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const readline = require('node:readline');
+
+const DEFAULT_BASE_URL = 'https://api.getmarrow.ai';
+const HIGH_RISK_TERMS = /\b(deploy|prod|production|publish|release|merge|migration|migrate|secret|token|key|cloudflare|wrangler|npm publish|gh pr merge|git push|terraform apply|kubectl apply|delete|destroy|drop)\b/i;
+const GOVERN_TUI_ROW_COUNT = 7;
+function usage() {
+  return `Usage:
+  npx @getmarrow/install run --agent deploy-agent -- npm test
+  npx @getmarrow/install run --agent deploy-agent --type deploy --policy enforce -- wrangler deploy
+  npx @getmarrow/install gate "deploy production worker"
+  npx @getmarrow/install proof --decision-id <id> --success --summary "smoke passed"
+  npx @getmarrow/install status
+  npx @getmarrow/install govern
+  npx @getmarrow/install govern --no-interactive
+
+Commands:
+  run       Run a command through Marrow pre-action gate and automatic outcome closure
+  gate      Check Marrow runtime/gate for an action without running a command
+  proof     Commit an outcome/proof for an existing decision
+  status    Read /v1/agent/status
+  govern    Interactive setup TUI when run in a terminal; text panel in CI/non-TTY
+
+Options:
+  --agent <id>            Agent identity. Defaults to MARROW_FLEET_AGENT_ID, MARROW_AGENT_ID, or local user
+  --session <id>          Session id. Defaults to marrow-run-<timestamp>
+  --type <type>           Action type. Inferred from action/command when omitted
+  --action <text>         Human-readable action. Defaults to the redacted command
+  --profile <name>        Policy profile label, such as dev, staging, or production
+  --policy <mode>         enforce, warn, or audit. Default: enforce
+  --fail-open             If Marrow is unreachable, run anyway and mark telemetry degraded
+  --fail-closed           If Marrow is unreachable, block the command
+  --owner-approved <ref>  Owner approval reference for review-required gates
+  --proof-file <path>     JSON proof to include on outcome commit
+  --base-url <url>        Marrow API base URL
+  --key <key>             Marrow API key. Prefer MARROW_API_KEY
+  --json                  Print machine-readable result after completion
+  --interactive           Force interactive govern TUI when possible
+  --no-interactive        Print govern panel instead of opening the TUI
+`;
+}
+
+function nowId(prefix) {
+  return `${prefix}-${new Date().toISOString().replace(/[^0-9TZ]/g, '')}-${crypto.randomBytes(4).toString('hex')}`;
+}
+
+function redact(value) {
+  let text = String(value || '');
+  text = text.replace(/\b[A-Z0-9_]*(?:TOKEN|SECRET|KEY|PASSWORD)[A-Z0-9_]*=([^\s]+)/gi, (match, captured) => match.replace(captured, '[redacted]'));
+  text = text.replace(/\bmrw_(?:live|test)_[A-Za-z0-9._-]+/g, '[redacted]');
+  text = text.replace(/\bnpm_[A-Za-z0-9._-]+/g, '[redacted]');
+  text = text.replace(/\bgh(?:p|o|u|s|r)_[A-Za-z0-9._-]+/g, '[redacted]');
+  text = text.replace(/\bsk-[A-Za-z0-9._-]+/g, '[redacted]');
+  return text;
+}
+
+function shellQuote(value) {
+  const text = String(value || '');
+  if (!text) return "''";
+  return /^[A-Za-z0-9_./:@%+=,-]+$/.test(text) ? text : `'${text.replace(/'/g, "'\\''")}'`;
+}
+
+function redactedCommand(command) {
+  return command.map((part) => shellQuote(redact(part))).join(' ');
+}
+
+function displayText(value, maxLength = 120) {
+  const text = redact(String(value || ''))
+    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
+    .replace(/\u009d[^\u0007\u009c]*(?:\u0007|\u009c|\u001b\\)/g, '')
+    .replace(/[\u001b\u009b][[\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '')
+    .replace(/[\t\r\n]+/g, ' ')
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, '');
+  return text.length > maxLength ? `${text.slice(0, maxLength - 3)}...` : text;
+}
+
+function shellQuoteDisplay(value) {
+  return shellQuote(displayText(value, 240));
+}
+
+function inferType(text) {
+  const value = String(text || '').toLowerCase();
+  if (/\b(deploy|wrangler|cloudflare|production|prod|release)\b/.test(value)) return 'deploy';
+  if (/\b(publish|npm publish)\b/.test(value)) return 'publish';
+  if (/\b(merge|gh pr merge)\b/.test(value)) return 'merge';
+  if (/\b(migration|migrate|schema|d1 execute|drop table)\b/.test(value)) return 'migration';
+  if (/\b(secret|token|key|password)\b/.test(value)) return 'security';
+  if (/\b(test|check|lint|typecheck|smoke)\b/.test(value)) return 'verification';
+  return 'general';
+}
+
+function inferSurfaces(text) {
+  const value = String(text || '').toLowerCase();
+  const surfaces = new Set();
+  if (/\b(git|gh|github)\b/.test(value)) surfaces.add('github');
+  if (/\b(wrangler|cloudflare|worker|d1|r2)\b/.test(value)) surfaces.add('cloudflare');
+  if (/\b(npm|pnpm|yarn|publish)\b/.test(value)) surfaces.add('npm');
+  if (/\b(sql|d1|migration|database|db)\b/.test(value)) surfaces.add('database');
+  if (/\b(curl|api|http)\b/.test(value)) surfaces.add('api');
+  if (surfaces.size === 0) surfaces.add('shell');
+  return [...surfaces];
+}
+
+function isRisky(text, type) {
+  return HIGH_RISK_TERMS.test(`${type || ''} ${text || ''}`);
+}
+
+function parseBaseOptions(argv, startIndex = 0) {
+  const options = {
+    apiKey: process.env.MARROW_API_KEY || process.env.MARROW_KEY || '',
+    baseUrl: process.env.MARROW_BASE_URL || DEFAULT_BASE_URL,
+    agentId: process.env.MARROW_FLEET_AGENT_ID || process.env.MARROW_AGENT_ID || os.userInfo().username || 'agent',
+    sessionId: process.env.MARROW_SESSION_ID || '',
+    profile: process.env.MARROW_GOVERN_PROFILE || 'default',
+    policy: process.env.MARROW_GOVERN_POLICY || 'enforce',
+    failOpen: process.env.MARROW_FAIL_OPEN === 'true',
+    failClosed: process.env.MARROW_FAIL_CLOSED === 'true',
+    json: false,
+    ownerApproval: '',
+    proofFile: '',
+    type: '',
+    action: '',
+    interactive: null,
+  };
+  let i = startIndex;
+  for (; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--') break;
+    if (arg === '--agent' || arg === '--agent-id') options.agentId = argv[++i] || options.agentId;
+    else if (arg === '--session' || arg === '--session-id') options.sessionId = argv[++i] || options.sessionId;
+    else if (arg === '--type') options.type = argv[++i] || options.type;
+    else if (arg === '--action') options.action = argv[++i] || options.action;
+    else if (arg === '--profile') options.profile = argv[++i] || options.profile;
+    else if (arg === '--policy') options.policy = argv[++i] || options.policy;
+    else if (arg === '--fail-open') {
+      options.failOpen = true;
+      options.failClosed = false;
+    } else if (arg === '--fail-closed') {
+      options.failClosed = true;
+      options.failOpen = false;
+    } else if (arg === '--owner-approved') options.ownerApproval = argv[++i] || options.ownerApproval;
+    else if (arg === '--proof-file') options.proofFile = argv[++i] || options.proofFile;
+    else if (arg === '--base-url') options.baseUrl = argv[++i] || options.baseUrl;
+    else if (arg === '--key') {
+      options.apiKey = argv[++i] || options.apiKey;
+      options.keyFromArg = true;
+    } else if (arg === '--json') options.json = true;
+    else if (arg === '--interactive') options.interactive = true;
+    else if (arg === '--no-interactive') options.interactive = false;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg.startsWith('--')) throw new Error(`Unknown option: ${arg}`);
+    else break;
+  }
+  if (!['enforce', 'warn', 'audit'].includes(options.policy)) {
+    throw new Error('--policy must be enforce, warn, or audit');
+  }
+  if (!options.sessionId) options.sessionId = nowId('marrow-run');
+  return { options, index: i };
+}
+
+function parseArgs(argv) {
+  const command = argv[0] || 'help';
+  if (command === '--help' || command === '-h' || command === 'help') return { command: 'help' };
+
+  if (command === 'run') {
+    const parsed = parseBaseOptions(argv, 1);
+    const separator = argv[parsed.index] === '--' ? parsed.index + 1 : parsed.index;
+    const childCommand = argv.slice(separator);
+    if (parsed.options.help) return { command: 'help' };
+    if (childCommand.length === 0) throw new Error('marrow run requires a command after --');
+    return { command, options: parsed.options, childCommand };
+  }
+
+  if (command === 'gate') {
+    const parsed = parseBaseOptions(argv, 1);
+    const action = parsed.options.action || argv.slice(parsed.index).join(' ');
+    if (parsed.options.help) return { command: 'help' };
+    if (!action) throw new Error('marrow gate requires an action string');
+    return { command, options: { ...parsed.options, action } };
+  }
+
+  if (command === 'proof') {
+    const parsed = parseBaseOptions(argv, 1);
+    const options = { ...parsed.options, decisionId: '', success: true, summary: '', outcome: '' };
+    for (let i = parsed.index; i < argv.length; i += 1) {
+      const arg = argv[i];
+      if (arg === '--decision-id') options.decisionId = argv[++i] || '';
+      else if (arg === '--success') options.success = true;
+      else if (arg === '--failure' || arg === '--failed') options.success = false;
+      else if (arg === '--summary') options.summary = argv[++i] || '';
+      else if (arg === '--outcome') options.outcome = argv[++i] || '';
+      else if (arg === '--help' || arg === '-h') return { command: 'help' };
+      else throw new Error(`Unknown proof option: ${arg}`);
+    }
+    if (!options.decisionId) throw new Error('marrow proof requires --decision-id');
+    return { command, options };
+  }
+
+  if (command === 'status' || command === 'govern') {
+    const parsed = parseBaseOptions(argv, 1);
+    if (parsed.options.help) return { command: 'help' };
+    return { command, options: parsed.options };
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+function headers(options) {
+  const h = {
+    Authorization: `Bearer ${options.apiKey}`,
+    'Content-Type': 'application/json',
+    'X-Marrow-Agent-Id': options.agentId,
+    'X-Marrow-Session-Id': options.sessionId,
+    'User-Agent': '@getmarrow/install governed-runner',
+  };
+  return h;
+}
+
+function dataOf(json) {
+  return json && typeof json === 'object' && json.data && typeof json.data === 'object' ? json.data : json;
+}
+
+async function requestJson(options, method, route, body) {
+  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),
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await response.text();
+  let json = {};
+  try { json = text ? JSON.parse(text) : {}; } catch { json = { error: text.slice(0, 500) }; }
+  if (!response.ok) {
+    const error = new Error(json.error || json.message || `Marrow ${route} returned HTTP ${response.status}`);
+    error.status = response.status;
+    error.details = json.details || json;
+    throw error;
+  }
+  return dataOf(json);
+}
+
+function proofFromFile(filePath) {
+  if (!filePath) return null;
+  const raw = fs.readFileSync(path.resolve(filePath), 'utf8');
+  return JSON.parse(raw);
+}
+
+function defaultProof(input) {
+  const proof = proofFromFile(input.options.proofFile) || {};
+  return {
+    summary: proof.summary || `Marrow governed runner completed ${input.action}.`,
+    checks: Array.isArray(proof.checks) ? proof.checks : ['marrow runtime gate', 'command exit captured'],
+    outcome: proof.outcome || (input.success ? 'success' : 'failure'),
+    blockers: Array.isArray(proof.blockers) ? proof.blockers : [],
+    command: redactedCommand(input.childCommand || []),
+    exit_code: input.exitCode,
+    runner: '@getmarrow/install run',
+    profile: input.options.profile,
+    ...(input.options.ownerApproval ? { owner_approval: { approved_by: 'owner', reference: input.options.ownerApproval } } : {}),
+    ...proof,
+  };
+}
+
+async function preflightRuntime(options, action, type, commandText) {
+  return requestJson(options, 'POST', '/v1/agent/runtime', {
+    action,
+    type,
+    surfaces: inferSurfaces(commandText || action),
+    context: {
+      runner: '@getmarrow/install run',
+      profile: options.profile,
+      command: commandText,
+      policy: options.policy,
+      governed: true,
+    },
+  });
+}
+
+function gateDecision(runtime) {
+  const gate = runtime?.risk_gate || {};
+  const receipt = runtime?.gate_receipt || {};
+  return {
+    decision: gate.enforcement_decision || receipt.decision || gate.decision || 'unknown',
+    allow: gate.allow !== false,
+    required: Boolean(receipt.required || gate.gate_required),
+    ownerApprovalRequired: Boolean(receipt.owner_approval_required || gate.owner_approval_required),
+    receiptId: receipt.id || gate.gate_receipt_id || '',
+    exactNextAction: runtime?.exact_next_action || receipt.exact_fix || gate.policy?.exact_fix || '',
+    beforeYouAct: runtime?.before_you_act_injection?.message || runtime?.before_you_act || '',
+    proofPack: runtime?.proof_pack || null,
+  };
+}
+
+function shouldBlock(decision, options) {
+  if (options.policy === 'audit') return false;
+  if (decision.decision === 'block' || decision.allow === false) return true;
+  if (options.policy === 'warn') return false;
+  if (decision.ownerApprovalRequired && !options.ownerApproval) return true;
+  if (decision.decision === 'owner_approval_required' && !options.ownerApproval) return true;
+  return false;
+}
+
+function printGate(decision, runtime, stream = process.stdout) {
+  stream.write(`Marrow gate: ${decision.decision}${decision.required ? ' (required)' : ''}\n`);
+  if (decision.beforeYouAct) stream.write(`Before you act: ${decision.beforeYouAct}\n`);
+  if (decision.exactNextAction) stream.write(`Next: ${decision.exactNextAction}\n`);
+  if (decision.proofPack?.required) {
+    const missing = decision.proofPack.missing?.length ? ` missing: ${decision.proofPack.missing.join(', ')}` : '';
+    stream.write(`Proof pack: required${missing}\n`);
+  }
+  if (runtime?.value_proof?.owner_summary) stream.write(`Value: ${runtime.value_proof.owner_summary}\n`);
+}
+
+function runChild(command, env = process.env) {
+  return new Promise((resolve) => {
+    const child = spawn(command[0], command.slice(1), {
+      stdio: 'inherit',
+      shell: false,
+      env,
+    });
+    child.on('error', (error) => resolve({ exitCode: 127, error }));
+    child.on('close', (code, signal) => resolve({ exitCode: code ?? 1, signal: signal || null }));
+  });
+}
+
+async function createDecision(options, action, type) {
+  return requestJson(options, 'POST', '/v1/agent/think', {
+    action,
+    type,
+    context: {
+      runner: '@getmarrow/install run',
+      profile: options.profile,
+      governed: true,
+    },
+  });
+}
+
+async function commitOutcome(options, decisionId, success, outcome, proof, gateReceiptId) {
+  const body = {
+    decision_id: decisionId,
+    success,
+    outcome,
+    proof,
+  };
+  if (gateReceiptId) body.gate_receipt_id = gateReceiptId;
+  return requestJson(options, 'POST', '/v1/agent/commit', body);
+}
+
+async function runGoverned(parsed) {
+  const { options, childCommand } = parsed;
+  const commandText = redactedCommand(childCommand);
+  const action = options.action ? redact(options.action) : commandText;
+  const type = options.type || inferType(`${action} ${commandText}`);
+  const risky = isRisky(`${action} ${commandText}`, type);
+  let runtime = null;
+  let decision = null;
+  let decisionId = '';
+
+  try {
+    runtime = await preflightRuntime(options, action, type, commandText);
+    decision = gateDecision(runtime);
+    printGate(decision, runtime);
+    if (shouldBlock(decision, options)) {
+      return {
+        ok: false,
+        blocked: true,
+        exitCode: 12,
+        action,
+        type,
+        risky,
+        decision,
+        message: decision.exactNextAction || 'Marrow blocked this action before execution.',
+      };
+    }
+    const think = await createDecision(options, action, type);
+    decisionId = think.decision_id || think.id || think.decision?.id || '';
+  } catch (error) {
+    if (options.failOpen || (!risky && !options.failClosed)) {
+      process.stderr.write(`Marrow degraded: ${error.message}. Continuing because fail-open/non-risky policy allows it.\n`);
+    } else {
+      return {
+        ok: false,
+        blocked: true,
+        degraded: true,
+        exitCode: 13,
+        action,
+        type,
+        risky,
+        message: error.message,
+      };
+    }
+  }
+
+  const child = await runChild(childCommand);
+  const success = child.exitCode === 0;
+  const proof = defaultProof({ options, action, childCommand, exitCode: child.exitCode, success });
+  const outcome = success
+    ? `Marrow governed command succeeded with exit code ${child.exitCode}.`
+    : `Marrow governed command failed with exit code ${child.exitCode}.`;
+
+  let commit = null;
+  if (decisionId) {
+    try {
+      commit = await commitOutcome(options, decisionId, success, outcome, proof, decision?.receiptId || '');
+    } catch (error) {
+      process.stderr.write(`Marrow outcome commit failed: ${error.message}\n`);
+    }
+  }
+
+  return {
+    ok: success,
+    blocked: false,
+    exitCode: child.exitCode,
+    action,
+    type,
+    risky,
+    decision,
+    decision_id: decisionId,
+    outcome_committed: Boolean(commit),
+  };
+}
+
+async function gateOnly(parsed) {
+  const { options } = parsed;
+  const action = redact(options.action);
+  const type = options.type || inferType(action);
+  const runtime = await preflightRuntime(options, action, type, action);
+  const decision = gateDecision(runtime);
+  printGate(decision, runtime);
+  return { ok: !shouldBlock(decision, options), action, type, decision };
+}
+
+async function proofOnly(parsed) {
+  const { options } = parsed;
+  const proof = defaultProof({
+    options,
+    action: options.summary || options.outcome || 'manual proof closeout',
+    childCommand: [],
+    exitCode: options.success ? 0 : 1,
+    success: options.success,
+  });
+  const result = await commitOutcome(
+    options,
+    options.decisionId,
+    options.success,
+    options.outcome || options.summary || (options.success ? 'Manual proof closeout succeeded.' : 'Manual proof closeout failed.'),
+    proof,
+    '',
+  );
+  return { ok: true, decision_id: options.decisionId, committed: true, result };
+}
+
+async function statusOnly(parsed) {
+  return requestJson(parsed.options, 'GET', '/v1/agent/status');
+}
+
+function detectHarnesses(cwd = process.cwd()) {
+  const candidates = [
+    { name: 'Codex', command: 'codex', detected: fs.existsSync(path.join(cwd, 'AGENTS.md')) || fs.existsSync(path.join(os.homedir(), '.codex')) },
+    { name: 'Claude Code', command: 'claude -p', detected: fs.existsSync(path.join(cwd, 'CLAUDE.md')) || fs.existsSync(path.join(os.homedir(), '.claude.json')) },
+    { name: 'Cursor', command: 'cursor', detected: fs.existsSync(path.join(cwd, '.cursor')) || fs.existsSync(path.join(os.homedir(), '.cursor')) },
+    { name: 'OpenCode', command: 'opencode', detected: fs.existsSync(path.join(cwd, 'opencode.json')) || fs.existsSync(path.join(os.homedir(), '.opencode')) },
+    { name: 'OpenClaw', command: 'openclaw agent', detected: fs.existsSync(path.join(os.homedir(), '.openclaw')) },
+    { name: 'CI script', command: 'npm test', detected: fs.existsSync(path.join(cwd, 'package.json')) },
+    { name: 'Custom command', command: '<your-agent-command>', detected: true },
+  ];
+  return candidates;
+}
+
+function governPanel(options) {
+  const rows = detectHarnesses();
+  const agentId = displayText(options.agentId, 80);
+  const profile = displayText(options.profile, 80);
+  const policy = displayText(options.policy, 24);
+  const lines = [
+    'Marrow Governed Runner',
+    '',
+    `Agent:  ${agentId}`,
+    `Profile: ${profile}`,
+    `Policy:  ${policy}`,
+    '',
+    'Choose where your agent runs. Marrow governs the action before it executes.',
+    '',
+    'Detected harnesses:',
+    ...rows.map((row, index) => `  ${index + 1}. ${row.detected ? '[x]' : '[ ]'} ${row.name}  ${row.command}`),
+    '',
+    'Recommended first commands:',
+    `  npx @getmarrow/install run --agent ${shellQuoteDisplay(options.agentId)} --profile production --policy enforce -- codex`,
+    `  npx @getmarrow/install run --agent deploy-agent --type deploy --policy enforce -- wrangler deploy`,
+    `  npx @getmarrow/install gate "deploy production worker after tests pass"`,
+    '',
+    'Protected by default: deploy, merge, publish, migrations, secrets, keys, production actions.',
+  ];
+  return lines.join('\n');
+}
+
+function governModes() {
+  return [
+    {
+      id: 'passive',
+      label: 'Passive setup',
+      description: 'Install passive MCP/SDK/agent instructions, then run the installer self-test.',
+      policy: 'warn',
+    },
+    {
+      id: 'warn',
+      label: 'Governed pilot',
+      description: 'Wrap commands with Marrow, show gates, but do not block execution.',
+      policy: 'warn',
+    },
+    {
+      id: 'enforce',
+      label: 'Governed enforce',
+      description: 'Wrap risky commands and fail closed when Marrow blocks or requires owner approval.',
+      policy: 'enforce',
+    },
+  ];
+}
+
+function commandForSelection(state, options) {
+  const harness = state.harnesses[state.harnessIndex] || state.harnesses[0];
+  const mode = state.modes[state.modeIndex] || state.modes[0];
+  if (mode.id === 'passive') {
+    return 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install --yes';
+  }
+  const command = harness.command === '<your-agent-command>' ? '<your-command>' : harness.command;
+  const renderedCommand = command.split(/\s+/).filter(Boolean).map(shellQuote).join(' ');
+  return `MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run --agent ${shellQuoteDisplay(options.agentId)} --profile ${shellQuoteDisplay(options.profile)} --policy ${shellQuoteDisplay(mode.policy)} -- ${renderedCommand}`;
+}
+
+function buildGovernState(options, cwd = process.cwd()) {
+  const harnesses = detectHarnesses(cwd);
+  const firstDetected = harnesses.findIndex((harness) => harness.detected);
+  return {
+    cursor: 0,
+    harnesses,
+    harnessIndex: firstDetected >= 0 ? firstDetected : 0,
+    modes: governModes(),
+    modeIndex: 0,
+    status: '',
+    lastResult: '',
+    confirmingSetup: false,
+    running: false,
+  };
+}
+
+function renderOptionBox(row, active) {
+  const contentWidth = 86;
+  const borderWidth = contentWidth + 2;
+  const marker = active ? '>' : ' ';
+  const borderChar = active ? '=' : '-';
+  const labelText = `[${displayText(row.label, 36)}]`;
+  const labelVisible = labelText.padEnd(38, ' ');
+  const label = `\x1b[47m\x1b[30m${labelText}\x1b[0m${' '.repeat(Math.max(0, 38 - labelText.length))}`;
+  const value = displayText(row.value, contentWidth - 39);
+  const firstLineVisible = `${labelVisible}${value}`;
+  const firstLine = `${label}${value}${' '.repeat(Math.max(0, contentWidth - firstLineVisible.length))}`;
+  const hint = displayText(row.hint, contentWidth);
+  return [
+    `${marker} +${borderChar.repeat(borderWidth)}+`,
+    `${marker} | ${firstLine} |`,
+    `${marker} | ${hint.padEnd(contentWidth, ' ')} |`,
+    `${marker} +${borderChar.repeat(borderWidth)}+`,
+  ];
+}
+
+function renderGovernTui(state, options) {
+  const harness = state.harnesses[state.harnessIndex] || state.harnesses[0];
+  const mode = state.modes[state.modeIndex] || state.modes[0];
+  const rows = [
+    {
+      label: 'Harness',
+      value: `${harness.name}${harness.detected ? ' detected' : ' not detected'} (${harness.command})`,
+      hint: 'Left/right changes the harness.',
+    },
+    {
+      label: 'Mode',
+      value: mode.label,
+      hint: mode.description,
+    },
+    {
+      label: 'Run passive setup + self-test',
+      value: state.confirmingSetup ? 'Press Enter again to run installer --yes' : 'writes local config after confirmation',
+      hint: 'Uses the existing installer path and self-test.',
+    },
+    {
+      label: 'Check Marrow status',
+      value: options.apiKey ? 'ready' : 'needs MARROW_API_KEY',
+      hint: 'Calls GET /v1/agent/status.',
+    },
+    {
+      label: 'Test before-action gate',
+      value: options.apiKey ? 'ready' : 'needs MARROW_API_KEY',
+      hint: 'Calls POST /v1/agent/runtime for a deploy-like action.',
+    },
+    {
+      label: 'Show command and exit',
+      value: 'Print selected command',
+      hint: 'Prints the command for this selection.',
+    },
+    {
+      label: 'Exit',
+      value: 'Return to shell',
+      hint: 'Press Enter, q, Esc, or Ctrl+C to leave setup.',
+    },
+  ];
+  const lines = [
+    '\x1b[2J\x1b[H',
+    '+------------------------------------------------------------+',
+    '| Marrow Governed Setup                                      |',
+    '| Passive agent governance for day-one use                   |',
+    '+------------------------------------------------------------+',
+    '',
+    `Agent: ${displayText(options.agentId, 36)}   Profile: ${displayText(options.profile, 24)}   API key: ${options.apiKey ? 'present' : 'missing'}`,
+    '',
+    'Navigation: Up/Down move   Left/Right change   Enter select',
+    'Exit: q, Esc, or Ctrl+C',
+    '',
+  ];
+  rows.forEach((row, index) => {
+    lines.push(...renderOptionBox(row, index === state.cursor), '');
+  });
+  lines.push('Recommended command:');
+  lines.push(`  ${commandForSelection(state, options)}`);
+  if (state.status) {
+    lines.push('');
+    lines.push(`Status: ${displayText(state.status, 120)}`);
+  }
+  if (state.lastResult) {
+    lines.push('');
+    lines.push(displayText(state.lastResult, 500));
+  }
+  return lines.join('\n');
+}
+
+function canUseInteractive(options, input = process.stdin, output = process.stdout) {
+  if (options.interactive === false) return false;
+  if (options.interactive === true) return Boolean(input.isTTY && output.isTTY);
+  return Boolean(input.isTTY && output.isTTY);
+}
+
+function waitForAnyKey(input = process.stdin) {
+  return new Promise((resolve) => {
+    const onKey = () => {
+      input.off('keypress', onKey);
+      resolve();
+    };
+    input.on('keypress', onKey);
+  });
+}
+
+async function runSetupSelfTest(options, input, output) {
+  if (!options.apiKey) {
+    return 'MARROW_API_KEY is missing. Create a key in your Marrow account, export it, then rerun setup.';
+  }
+  const binPath = path.resolve(__dirname, '..', 'bin', 'marrow-install.js');
+  output.write('\x1b[2J\x1b[HRunning Marrow passive setup and self-test...\n\n');
+  if (input.setRawMode) input.setRawMode(false);
+  const result = await runChild([process.execPath, binPath, '--yes'], {
+    ...process.env,
+    MARROW_API_KEY: options.apiKey,
+    MARROW_BASE_URL: options.baseUrl,
+    MARROW_FLEET_AGENT_ID: options.agentId,
+  });
+  output.write('\nPress any key to return to Marrow Governed Setup.');
+  if (input.setRawMode) input.setRawMode(true);
+  await waitForAnyKey(input);
+  return result.exitCode === 0
+    ? 'Marrow passive setup completed. Self-test output above is the source of truth.'
+    : `Marrow passive setup exited with code ${result.exitCode}. Review the output above.`;
+}
+
+async function runStatusCheck(options) {
+  if (!options.apiKey) return 'MARROW_API_KEY is missing. Status check skipped.';
+  const status = await statusOnly({ options });
+  const coverage = status.capture_coverage || {};
+  const closure = status.auto_outcome_closure || {};
+  const active = status.enabled ?? status.active ?? true;
+  const missed = Array.isArray(status.missed_hooks) && status.missed_hooks.length
+    ? ` missed hooks: ${status.missed_hooks.join(', ')}`
+    : '';
+  return `Marrow status: ${active ? 'active' : 'inactive'}; coverage=${coverage.status || coverage.summary || 'reported'}; outcomes=${closure.status || closure.summary || 'reported'}${missed}`;
+}
+
+async function runGateCheck(options) {
+  if (!options.apiKey) return 'MARROW_API_KEY is missing. Gate check skipped.';
+  const runtime = await preflightRuntime(options, 'deploy production worker after tests pass', 'deploy', 'wrangler deploy');
+  const decision = gateDecision(runtime);
+  const proof = decision.proofPack?.required
+    ? ` Proof required${decision.proofPack.missing?.length ? `; missing ${decision.proofPack.missing.join(', ')}` : ''}.`
+    : '';
+  return `Gate: ${decision.decision}${decision.required ? ' required' : ''}.${decision.exactNextAction ? ` Next: ${decision.exactNextAction}` : ''}${proof}`;
+}
+
+async function runGovernInteractive(options, input = process.stdin, output = process.stdout) {
+  if (!canUseInteractive(options, input, output)) {
+    output.write(`${governPanel(options)}\n`);
+    return;
+  }
+
+  const state = buildGovernState(options);
+  readline.emitKeypressEvents(input);
+  input.setRawMode(true);
+  output.write('\x1b[?25l');
+
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    if (input.setRawMode) input.setRawMode(false);
+    output.write('\x1b[?25h');
+  };
+
+  const render = () => {
+    output.write(renderGovernTui(state, options));
+  };
+
+  render();
+  let keyHandler;
+  try {
+    await new Promise((resolve) => {
+      keyHandler = async (str, key = {}) => {
+        if (state.running) return;
+        if (key.ctrl && key.name === 'c') {
+          cleanup();
+          resolve();
+          return;
+        }
+        if (key.name === 'q' || key.name === 'escape' || str === 'q') {
+          cleanup();
+          resolve();
+          return;
+        }
+        if (key.name === 'up') {
+          state.cursor = (state.cursor + GOVERN_TUI_ROW_COUNT - 1) % GOVERN_TUI_ROW_COUNT;
+          state.confirmingSetup = false;
+          render();
+        } else if (key.name === 'down') {
+          state.cursor = (state.cursor + 1) % GOVERN_TUI_ROW_COUNT;
+          state.confirmingSetup = false;
+          render();
+        } else if (key.name === 'left' || key.name === 'right') {
+          const direction = key.name === 'right' ? 1 : -1;
+          if (state.cursor === 0) state.harnessIndex = (state.harnessIndex + direction + state.harnesses.length) % state.harnesses.length;
+          if (state.cursor === 1) state.modeIndex = (state.modeIndex + direction + state.modes.length) % state.modes.length;
+          state.confirmingSetup = false;
+          render();
+        } else if (key.name === 'return') {
+          state.running = true;
+          try {
+            if (state.cursor === 0) {
+              state.harnessIndex = (state.harnessIndex + 1) % state.harnesses.length;
+              state.status = 'Harness selected.';
+              state.confirmingSetup = false;
+            } else if (state.cursor === 1) {
+              state.modeIndex = (state.modeIndex + 1) % state.modes.length;
+              state.status = 'Mode selected.';
+              state.confirmingSetup = false;
+            } else if (state.cursor === 2) {
+              if (!state.confirmingSetup) {
+                state.confirmingSetup = true;
+                state.status = 'Confirm passive setup.';
+              } else {
+                state.lastResult = await runSetupSelfTest(options, input, output);
+                state.status = 'Passive setup attempted.';
+                state.confirmingSetup = false;
+              }
+            } else if (state.cursor === 3) {
+              state.status = 'Checking Marrow status...';
+              render();
+              state.lastResult = await runStatusCheck(options);
+              state.status = 'Status check complete.';
+              state.confirmingSetup = false;
+            } else if (state.cursor === 4) {
+              state.status = 'Testing before-action gate...';
+              render();
+              state.lastResult = await runGateCheck(options);
+              state.status = 'Gate check complete.';
+              state.confirmingSetup = false;
+            } else if (state.cursor === 5) {
+              cleanup();
+              output.write(`\n${commandForSelection(state, options)}\n`);
+              resolve();
+              return;
+            } else if (state.cursor === 6) {
+              cleanup();
+              resolve();
+              return;
+            }
+          } catch (error) {
+            state.lastResult = `Error: ${error instanceof Error ? error.message : String(error)}`;
+            state.status = 'Action failed.';
+            state.confirmingSetup = false;
+          } finally {
+            state.running = false;
+            if (!cleaned) render();
+          }
+        }
+      };
+      input.on('keypress', keyHandler);
+    });
+  } finally {
+    if (keyHandler) input.off('keypress', keyHandler);
+    if (input.pause) input.pause();
+    cleanup();
+    output.write('\n');
+  }
+}
+
+async function runCli(argv) {
+  const parsed = parseArgs(argv);
+  if (parsed.command === 'help') {
+    process.stdout.write(usage());
+    return;
+  }
+
+  if (parsed.options?.keyFromArg) {
+    process.stderr.write('Warning: prefer MARROW_API_KEY instead of --key because command-line args can be visible in process listings.\n');
+  }
+
+  let result;
+  if (parsed.command === 'run') result = await runGoverned(parsed);
+  else if (parsed.command === 'gate') result = await gateOnly(parsed);
+  else if (parsed.command === 'proof') result = await proofOnly(parsed);
+  else if (parsed.command === 'status') result = await statusOnly(parsed);
+  else if (parsed.command === 'govern') {
+    await runGovernInteractive(parsed.options);
+    return;
+  }
+
+  if (parsed.options?.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else if (result?.blocked) process.stderr.write(`BLOCKED: ${result.message || 'Marrow blocked this action.'}\n`);
+  else if (parsed.command !== 'run') process.stdout.write('Marrow command completed.\n');
+
+  if (parsed.command === 'run' || result?.blocked) process.exitCode = result?.exitCode ?? (result?.ok === false ? 1 : 0);
+}
+
+module.exports = {
+  parseArgs,
+  redact,
+  redactedCommand,
+  inferType,
+  inferSurfaces,
+  commandForSelection,
+  buildGovernState,
+  gateDecision,
+  shouldBlock,
+  governPanel,
+  renderGovernTui,
+  canUseInteractive,
+  runGoverned,
+  gateOnly,
+  proofOnly,
+  statusOnly,
+  runStatusCheck,
+  runGateCheck,
+  runGovernInteractive,
+  runCli,
+};

package/src/installer.js

@@ -105,6 +105,12 @@ 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);
 }