@getmarrow/install 0.1.35 → 0.1.37

package/src/governed-runner.js

@@ -5,9 +5,84 @@ const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
 const { version: INSTALLER_PACKAGE_VERSION } = require('../package.json');
+const {
+  actionBinding,
+  closeActionPermit,
+  issueActionPermit,
+  readEnforcementCoverage,
+  recordEnforcementHeartbeat,
+  verifyActionPermit,
+} = require('./enforcement-client');
+const { startGovernanceSidecar } = require('./governance-sidecar');
+const {
+  controllerStatus,
+  ensureGovernanceController,
+  startGovernanceController,
+  stopGovernanceController,
+} = require('./controller-manager');
+const {
+  HARNESS_CAPABILITY_REGISTRY,
+  applyPlan,
+  buildPlan,
+  detectEnvironment,
+} = require('./installer');
 
 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 PROTECTED_COMMAND_PATTERNS = [
+  /\b(?:npm|pnpm|yarn)(?:\s+npm)?\b[\s\S]{0,8192}\b(?:publish|unpublish|deprecate|access|owner|team|token|login|logout|profile\s+(?:set|enable-2fa|disable-2fa)|dist-tag|tag\s+(?:add|remove))\b/i,
+  /\b(?:cargo\s+(?:publish|yank|owner)|twine\s+upload|gem\s+(?:push|yank|owner)|(?:dotnet\s+nuget|nuget)\s+(?:push|delete))\b/i,
+  /\bgit\b[\s\S]{0,8192}\b(?:push|commit|merge|rebase|reset|tag|clean|rm|cherry-pick|revert|worktree\s+(?:add|move|remove|prune|repair|lock|unlock)|branch\s+(?:-[dDmM]|--delete|--move)|remote\s+(?:add|remove|rename|set-url|set-head|prune|update)|checkout\s+-[bB]|switch\s+-[cC])\b/i,
+  /\bgh\b[\s\S]{0,8192}\b(?:auth\s+logout|pr\s+(?:merge|close|reopen|edit|review|comment)|issue\s+(?:create|close|reopen|edit|comment)|run\s+(?:cancel|delete|rerun)|release\s+(?:create|delete|edit|upload)|repo\s+(?:archive|delete|edit|fork|rename)|workflow\s+run|secret\s+(?:set|delete)|variable\s+(?:set|delete))\b/i,
+  /\bgh\s+api\b[\s\S]{0,8192}(?:(?:--method|-X)(?:=|\s+)(?:POST|PUT|PATCH|DELETE)\b|(?:-f|-F|--field|--raw-field|--input)(?:=|\s+))/i,
+  /\b(?:kubectl|oc)\b[\s\S]{0,8192}\b(?:apply|create|delete|edit|patch|replace|rollout|scale|set|drain|cordon|uncordon|taint|exec|cp|run|expose|autoscale|label|annotate|reconcile|certificate\s+(?:approve|deny))\b/i,
+  /\b(?:terraform|terragrunt|tofu)\b[\s\S]{0,8192}\b(?:apply|destroy|import|taint|untaint|force-unlock|state\s+(?:mv|rm|push|replace-provider)|workspace\s+(?:new|delete))\b/i,
+  /\bpulumi\b[\s\S]{0,8192}\b(?:up|destroy|import|refresh|stack\s+rm|config\s+(?:set|rm))\b/i,
+  /\bhelm\b[\s\S]{0,8192}\b(?:install|upgrade|uninstall|rollback|push)\b/i,
+  /\bflux\b[\s\S]{0,8192}\b(?:bootstrap|create|delete|install|reconcile|resume|suspend|tag|uninstall)\b/i,
+  /\bnomad\b[\s\S]{0,8192}\b(?:job\s+(?:dispatch|plan|promote|run|scale|stop)|alloc\s+stop|deployment\s+(?:fail|promote)|acl\s+(?:bootstrap|policy|role|token))\b/i,
+  /\bcdk\b[\s\S]{0,8192}\b(?:bootstrap|deploy|destroy|import|rollback)\b/i,
+  /\bansible-playbook\b/i,
+  /\b(?:docker|podman)\b[\s\S]{0,8192}\b(?:push|buildx\s+build\b[\s\S]*--push)\b/i,
+  /\bwrangler\b[\s\S]{0,8192}\b(?:deploy|delete|rollback|execute|apply|put|bulk|secret|publish)\b/i,
+  /\bcurl\b[\s\S]{0,8192}(?:(?:-X\s*|--request(?:=|\s+))(?:POST|PUT|PATCH|DELETE)\b|--(?:json|data(?:-ascii|-raw|-binary|-urlencode)?)(?:=|\s+)|-[dF](?:\s+|[^A-Za-z])|--form(?:-string)?(?:=|\s+)|(?:-T|--upload-file)(?:=|\s+))/i,
+  /\b(?:http|xh)\b[\s\S]{0,8192}(?:\b(?:POST|PUT|PATCH|DELETE)\b|(?:--form|--raw|-f)\b|\s[^\s=:@]+(?::=|=|@))/i,
+  /\bwget\b[\s\S]{0,8192}(?:--post-data|--post-file|--body-data|--body-file|--method(?:=|\s+)(?:POST|PUT|PATCH|DELETE))\b/i,
+  /\b(?:psql|mysql|sqlite3|duckdb)\b[\s\S]{0,8192}(?:\b(?:drop|delete|update|insert|alter|truncate|create|grant|revoke|call|do)\b|(?:-f|--file|\.read|source)(?:=|\s+)|\s<\s*[^\s])/i,
+  /\bredis-cli\b[\s\S]{0,8192}\b(?:set|setex|psetex|mset|del|unlink|getdel|incr|decr|append|expire|persist|rename|move|flushall|flushdb|shutdown|eval|evalsha|fcall|fcall_ro|function|script\s+(?:load|flush|kill)|config\s+set|acl\s+setuser|hset|hdel|lpush|rpush|lpop|rpop|sadd|srem|zadd|zrem|xadd|xdel|publish|restore|migrate)\b/i,
+  /\baws\b[\s\S]{0,8192}\b(?:create|update|delete|put|attach|detach|associate|disassociate|terminate|stop|start|reboot|modify|restore|rotate|tag|untag|deploy|sync|s3\s+(?:cp|mv|rm)|s3api\s+put-object|ssm\s+(?:put-parameter|delete-parameter|delete-parameters))\b/i,
+  /\bgcloud\b[\s\S]{0,8192}\b(?:create|update|delete|deploy|add|remove|set|destroy|disable|restore|storage\s+(?:cp|mv|rm|rsync)|pubsub\s+(?:topics|subscriptions)\s+(?:create|delete|update))\b/i,
+  /\baz\b[\s\S]{0,8192}\b(?:create|update|delete|set|deploy|start|stop|restart|restore|storage\s+blob\s+(?:upload|delete|copy)|group\s+(?:create|delete|update))\b/i,
+  /\brclone\b[\s\S]{0,8192}\b(?:copy|copyto|sync|move|moveto|delete|deletefile|purge|mkdir|rmdir|bisync)\b/i,
+  /\bgsutil\b[\s\S]{0,8192}\b(?:cp|mv|rm|rsync|setacl|setmeta|web)\b/i,
+  /(?:^|[;&|]\s*|\bsudo\s+|\benv\s+)mc\b[\s\S]{0,8192}\b(?:cp|mv|rm|mirror|mb|rb|anonymous|admin)\b/i,
+  /\boci\b[\s\S]{0,8192}\bos\b[\s\S]{0,8192}\b(?:put|upload|bulk-upload|delete|rename|restore|reencrypt)\b/i,
+  /\b(?:vault|op)\b[\s\S]{0,8192}\b(?:write|put|patch|delete|edit|create|move|rotate|revoke|destroy|share)\b/i,
+  /\bpass\b[\s\S]{0,8192}\b(?:insert|edit|generate|rm|remove|mv|cp|init|git)\b/i,
+  /(?:^|[\s;&|]|\bsudo\s+|\benv\s+)(?:(?:\/[^\s/]+)*\/)?(?:rm\b|unlink\b|shred\b|truncate\b|dd\b[\s\S]{0,8192}\bof=|find\b[\s\S]{0,8192}\s-delete\b|xargs\b[\s\S]{0,8192}(?:(?:\/[^\s/]+)*\/)?rm\b)/i,
+];
+const PROTECTED_ACTION_TYPES = new Set([
+  'credential',
+  'credentials',
+  'deploy',
+  'financial',
+  'merge',
+  'migration',
+  'production',
+  'publish',
+  'release',
+  'secret',
+  'security',
+]);
+const SAFE_MARROW_CHILD_METADATA = new Set([
+  'MARROW_AGENT_ID',
+  'MARROW_AGENT_CLIENT',
+  'MARROW_CLIENT',
+  'MARROW_FLEET_AGENT_ID',
+  'MARROW_GOVERN_PROFILE',
+  'MARROW_HARNESS',
+  'MARROW_SESSION_ID',
+]);
 const GOVERN_TUI_ROW_COUNT = 7;
 const FLEET_TUI_ROW_COUNT = 12;
 function usage() {
@@ -17,6 +92,10 @@ function usage() {
   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 permit --action "deploy production" --type deploy
+  MARROW_ACTION_PERMIT=... npx @getmarrow/install verify-permit --action "deploy production" --type deploy
+  npx @getmarrow/install coverage
+  npx @getmarrow/install sidecar
   npx @getmarrow/install govern
   npx @getmarrow/install govern --no-interactive
   npx @getmarrow/install fleet
@@ -29,6 +108,12 @@ Commands:
   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
+  permit    Issue a short-lived action-bound permit after Marrow policy evaluation
+  verify-permit Verify a permit before CI, deploy, publish, merge, migration, or credential access
+  coverage  Show enforcement, hook-health, closure, and bypass coverage
+  sidecar   Run the loopback-only Marrow governance sidecar
+  controller <ensure|start|status|stop>
+            Keep the loopback governance controller active across agent sessions
   govern    Interactive setup TUI when run in a terminal; text panel in CI/non-TTY
   fleet     Fleet operator TUI for live agents, workflows, gates, proof debt, and exact fixes
   integrations List Marrow-supported harness add-ons
@@ -42,9 +127,12 @@ Options:
   --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-open             For non-protected, low-risk actions only, run if Marrow is unreachable
   --fail-closed           If Marrow is unreachable, block the command
   --owner-approved <ref>  Owner approval reference for review-required gates
+  --permit <token>        Short-lived action permit. Prefer MARROW_ACTION_PERMIT
+  --target <text>         Protected target binding, such as repository/environment
+  --sidecar-port <port>   Loopback sidecar port. Default: ephemeral
   --proof-file <path>     JSON proof to include on outcome commit
   --client <label>        Harness/client label. Defaults to MARROW_CLIENT, MARROW_HARNESS, or MARROW_AGENT_CLIENT
   --base-url <url>        Marrow API base URL
@@ -79,6 +167,14 @@ function redactedCommand(command) {
   return command.map((part) => shellQuote(redact(part))).join(' ');
 }
 
+function isProtectedCommand(text) {
+  const raw = String(text || '');
+  if (raw.length > 8192) return true;
+  const value = raw.slice(0, 8192);
+  return HIGH_RISK_TERMS.test(value)
+    || PROTECTED_COMMAND_PATTERNS.some((pattern) => pattern.test(value));
+}
+
 function normalizeClientLabel(value) {
   const raw = String(value || '').trim().toLowerCase();
   if (!raw) return '';
@@ -129,9 +225,11 @@ function shellQuoteDisplay(value) {
 
 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(deploy|wrangler|cloudflare|production|prod|release)\b/.test(value)
+    || /\b(?:kubectl|terraform|pulumi|helm)\b/.test(value) && isProtectedCommand(value)) return 'deploy';
+  if (/\b(publish|unpublish|deprecate|npm publish)\b/.test(value)) return 'publish';
+  if (/\b(merge|gh pr merge)\b/.test(value)
+    || /\bgit\b[^\n;&|]{0,240}\bpush\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';
@@ -143,6 +241,7 @@ function inferSurfaces(text) {
   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(kubectl|terraform|pulumi|helm|production|prod)\b/.test(value)) surfaces.add('production');
   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');
@@ -232,7 +331,8 @@ function detectProjectSignals(cwd = process.cwd()) {
 }
 
 function isRisky(text, type) {
-  return HIGH_RISK_TERMS.test(`${type || ''} ${text || ''}`);
+  return PROTECTED_ACTION_TYPES.has(String(type || '').trim().toLowerCase())
+    || isProtectedCommand(`${type || ''} ${text || ''}`);
 }
 
 function parseBaseOptions(argv, startIndex = 0) {
@@ -252,6 +352,9 @@ function parseBaseOptions(argv, startIndex = 0) {
     action: '',
     client: sourceClient(),
     interactive: null,
+    permit: process.env.MARROW_ACTION_PERMIT || '',
+    target: process.env.MARROW_ACTION_TARGET || '',
+    sidecarPort: process.env.MARROW_SIDECAR_PORT || '0',
   };
   let i = startIndex;
   for (; i < argv.length; i += 1) {
@@ -270,6 +373,9 @@ function parseBaseOptions(argv, startIndex = 0) {
       options.failClosed = true;
       options.failOpen = false;
     } else if (arg === '--owner-approved') options.ownerApproval = argv[++i] || options.ownerApproval;
+    else if (arg === '--permit') options.permit = argv[++i] || options.permit;
+    else if (arg === '--target') options.target = argv[++i] || options.target;
+    else if (arg === '--sidecar-port') options.sidecarPort = argv[++i] || options.sidecarPort;
     else if (arg === '--proof-file') options.proofFile = argv[++i] || options.proofFile;
     else if (arg === '--client' || arg === '--harness') options.client = sourceClient(argv[++i] || options.client);
     else if (arg === '--base-url') options.baseUrl = argv[++i] || options.baseUrl;
@@ -311,6 +417,17 @@ function parseArgs(argv) {
     return { command, options: { ...parsed.options, action } };
   }
 
+  if (command === 'permit' || command === 'verify-permit') {
+    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(`${command} requires --action or an action string`);
+    if (command === 'verify-permit' && !parsed.options.permit) {
+      throw new Error('verify-permit requires MARROW_ACTION_PERMIT or --permit');
+    }
+    return { command, options: { ...parsed.options, action } };
+  }
+
   if (command === 'proof') {
     const parsed = parseBaseOptions(argv, 1);
     const options = { ...parsed.options, decisionId: '', success: true, summary: '', outcome: '' };
@@ -328,7 +445,17 @@ function parseArgs(argv) {
     return { command, options };
   }
 
-  if (command === 'status' || command === 'govern' || command === 'fleet' || command === 'hermes' || command === 'openclaw' || command === 'integrations') {
+  if (command === 'controller') {
+    const action = argv[1] && !argv[1].startsWith('--') ? argv[1] : 'status';
+    if (!['ensure', 'start', 'status', 'stop'].includes(action)) {
+      throw new Error('controller action must be ensure, start, status, or stop');
+    }
+    const parsed = parseBaseOptions(argv, action === 'status' && argv[1] !== 'status' ? 1 : 2);
+    if (parsed.options.help) return { command: 'help' };
+    return { command, action, options: parsed.options };
+  }
+
+  if (command === 'status' || command === 'govern' || command === 'fleet' || command === 'hermes' || command === 'openclaw' || command === 'integrations' || command === 'coverage' || command === 'sidecar') {
     const parsed = parseBaseOptions(argv, 1);
     if (parsed.options.help) return { command: 'help' };
     return { command, options: parsed.options };
@@ -414,11 +541,14 @@ function defaultProof(input) {
 }
 
 async function preflightRuntime(options, action, type, commandText) {
+  const target = options.target || commandText || action;
+  const surfaces = inferSurfaces(commandText || action);
   const meta = sourceMeta(options, 'runtime', { action, command: commandText, action_type: type });
   return requestJson(options, 'POST', '/v1/agent/runtime', {
     action,
     type,
-    surfaces: inferSurfaces(commandText || action),
+    target,
+    surfaces,
     source_meta: meta,
     context: {
       runner: '@getmarrow/install run',
@@ -484,6 +614,7 @@ function gateDecision(runtime) {
   return {
     decision: gate.enforcement_decision || receipt.decision || gate.decision || 'unknown',
     allow: gate.allow !== false,
+    riskLevel: String(gate.risk_level || receipt.risk_level || runtime?.risk_level || '').trim().toLowerCase(),
     required: Boolean(receipt.required || gate.gate_required),
     ownerApprovalRequired: Boolean(receipt.owner_approval_required || gate.owner_approval_required),
     receiptId: receipt.id || gate.gate_receipt_id || '',
@@ -525,11 +656,28 @@ function runChild(command, env = process.env) {
   });
 }
 
-async function createDecision(options, action, type) {
+function scopedExecutionEnv(permit) {
+  const env = {};
+  for (const [name, value] of Object.entries(process.env)) {
+    if (name.startsWith('MARROW_') && !SAFE_MARROW_CHILD_METADATA.has(name)) continue;
+    if (name.startsWith('ACTION_PERMIT_')) continue;
+    env[name] = value;
+  }
+  if (permit?.permit) {
+    env.MARROW_ACTION_PERMIT = permit.permit;
+    env.MARROW_ACTION_PERMIT_ID = String(permit.permit_id || '');
+    env.MARROW_GOVERNANCE_VERIFIED = 'true';
+  }
+  return env;
+}
+
+async function createDecision(options, action, type, target, surfaces) {
   const meta = sourceMeta(options, 'think', { action, action_type: type });
   return requestJson(options, 'POST', '/v1/agent/think', {
     action,
     type,
+    target,
+    surfaces,
     source_meta: meta,
     context: {
       runner: '@getmarrow/install run',
@@ -556,15 +704,25 @@ 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);
+  const riskText = `${action} ${commandText} ${options.target || ''}`;
+  const type = options.type || inferType(riskText);
+  const risky = isRisky(riskText, type);
   let runtime = null;
   let decision = null;
   let decisionId = '';
+  let actionPermit = null;
+  let permitVerified = false;
+  let degraded = false;
+  let protectedAction = risky;
+  const surfaces = inferSurfaces(commandText || action);
 
   try {
     runtime = await preflightRuntime(options, action, type, commandText);
     decision = gateDecision(runtime);
+    protectedAction = risky
+      || decision?.required === true
+      || decision?.riskLevel === 'high'
+      || decision?.riskLevel === 'critical';
     printGate(decision, runtime);
     if (shouldBlock(decision, options)) {
       return {
@@ -578,10 +736,40 @@ async function runGoverned(parsed) {
         message: decision.exactNextAction || 'Marrow blocked this action before execution.',
       };
     }
-    const think = await createDecision(options, action, type);
+    const target = options.target || commandText;
+    const think = await createDecision(options, action, type, target, surfaces);
     decisionId = think.decision_id || think.id || think.decision?.id || '';
+    if (protectedAction) {
+      actionPermit = await issueActionPermit(requestJson, options, {
+        action,
+        type,
+        target,
+        surfaces,
+        decisionId,
+        gateReceiptId: decision?.receiptId || '',
+        ownerApproval: options.ownerApproval,
+        proofRequirements: decision?.proofPack?.required_fields || decision?.proofPack?.missing || [],
+      });
+      if (!actionPermit?.permit || !actionPermit?.permit_id) {
+        throw new Error('Marrow did not issue a valid action permit.');
+      }
+      const verified = await verifyActionPermit(requestJson, options, {
+        action,
+        type,
+        target,
+        surfaces,
+        permit: actionPermit.permit,
+      });
+      if (verified?.verified !== true) throw new Error('Marrow action permit verification failed.');
+      permitVerified = true;
+    }
   } catch (error) {
-    if (options.failOpen || (!risky && !options.failClosed)) {
+    const canDegrade = !protectedAction
+      && (options.failOpen || !options.failClosed);
+    if (canDegrade) {
+      actionPermit = null;
+      permitVerified = false;
+      degraded = true;
       process.stderr.write(`Marrow degraded: ${error.message}. Continuing because fail-open/non-risky policy allows it.\n`);
     } else {
       return {
@@ -597,7 +785,8 @@ async function runGoverned(parsed) {
     }
   }
 
-  const child = await runChild(childCommand);
+  const childEnv = scopedExecutionEnv(permitVerified ? actionPermit : null);
+  const child = await runChild(childCommand, childEnv);
   const success = child.exitCode === 0;
   const proof = defaultProof({ options, action, childCommand, exitCode: child.exitCode, success });
   const outcome = success
@@ -613,6 +802,21 @@ async function runGoverned(parsed) {
     }
   }
 
+  let permitClosed = null;
+  if (actionPermit?.permit) {
+    try {
+      permitClosed = await closeActionPermit(requestJson, options, {
+        permit: actionPermit.permit,
+        permitId: actionPermit.permit_id,
+        decisionId,
+        success,
+        evidence: proof,
+      });
+    } catch (error) {
+      process.stderr.write(`Marrow permit close failed: ${error.message}\n`);
+    }
+  }
+
   return {
     ok: success,
     blocked: false,
@@ -620,10 +824,110 @@ async function runGoverned(parsed) {
     action,
     type,
     risky,
+    degraded,
     decision,
     decision_id: decisionId,
     outcome_committed: Boolean(commit),
+    permit_id: actionPermit?.permit_id || null,
+    permit_verified: permitVerified,
+    permit_closed: Boolean(permitClosed),
+  };
+}
+
+async function permitOnly(parsed) {
+  const { options } = parsed;
+  const action = redact(options.action);
+  const type = options.type || inferType(action);
+  const target = options.target || action;
+  const surfaces = inferSurfaces(target);
+  const runtime = await preflightRuntime(options, action, type, target);
+  const decision = gateDecision(runtime);
+  if (shouldBlock(decision, options)) {
+    return { ok: false, blocked: true, exitCode: 12, decision, message: decision.exactNextAction };
+  }
+  const think = await createDecision(options, action, type, target, surfaces);
+  const decisionId = think.decision_id || think.id || think.decision?.id || '';
+  const result = await issueActionPermit(requestJson, options, {
+    action,
+    type,
+    target,
+    surfaces,
+    decisionId,
+    gateReceiptId: decision.receiptId,
+    ownerApproval: options.ownerApproval,
+    proofRequirements: decision?.proofPack?.required_fields || decision?.proofPack?.missing || [],
+  });
+  return { ok: true, decision_id: decisionId, ...result };
+}
+
+async function verifyPermitOnly(parsed) {
+  const { options } = parsed;
+  const action = redact(options.action);
+  const type = options.type || inferType(action);
+  const surfaces = inferSurfaces(options.target || action);
+  const result = await verifyActionPermit(requestJson, options, {
+    action,
+    type,
+    target: options.target || action,
+    surfaces,
+    permit: options.permit,
+  });
+  const verified = result?.verified === true;
+  return { ...result, ok: verified, exitCode: verified ? 0 : 14 };
+}
+
+async function coverageOnly(parsed) {
+  return readEnforcementCoverage(requestJson, parsed.options);
+}
+
+async function sidecarOnly(parsed) {
+  const options = parsed.options;
+  const root = path.resolve(process.env.MARROW_CONTROLLER_PROJECT_ROOT || process.cwd());
+  const managedMode = process.env.MARROW_CONTROLLER_MANAGED_MODE || 'auto';
+  let lastMaintenanceAt = 0;
+  let lastMaintenance = null;
+  const maintain = async () => {
+    if (lastMaintenance && Date.now() - lastMaintenanceAt < 5 * 60_000) return lastMaintenance;
+    const detection = detectEnvironment(root, process.env);
+    const plan = buildPlan(detection, { mode: managedMode });
+    const changes = applyPlan(plan, { yes: true, dryRun: false, doctor: false });
+    const repaired = changes.filter((change) => change.applied).map((change) => change.label);
+    const remaining = changes.filter((change) => change.changed && !change.applied).map((change) => change.label);
+    lastMaintenanceAt = Date.now();
+    lastMaintenance = {
+      state: remaining.length > 0 ? 'attention_required' : repaired.length > 0 ? 'repaired' : 'clear',
+      checked_at: new Date(lastMaintenanceAt).toISOString(),
+      repaired,
+      exact_fix: remaining.length > 0 ? 'Run npx @getmarrow/install --repair in the managed project.' : null,
+    };
+    return lastMaintenance;
   };
+  const sidecar = await startGovernanceSidecar(options, {
+    permit: (input) => issueActionPermit(requestJson, options, input),
+    verify: (input) => verifyActionPermit(requestJson, options, input),
+    close: (input) => closeActionPermit(requestJson, options, input),
+    coverage: () => readEnforcementCoverage(requestJson, options),
+    heartbeat: (input) => recordEnforcementHeartbeat(requestJson, options, input),
+    maintain,
+  });
+  process.stdout.write(`Marrow governance sidecar active on 127.0.0.1:${sidecar.port}. Press Ctrl+C to stop.\n`);
+  await new Promise((resolve) => sidecar.server.once('close', resolve));
+  return { ok: true };
+}
+
+async function controllerOnly(parsed) {
+  const options = { ...parsed.options, root: process.cwd(), mode: 'auto' };
+  let result;
+  if (parsed.action === 'ensure') result = await ensureGovernanceController(options);
+  else if (parsed.action === 'start') result = await startGovernanceController(options);
+  else if (parsed.action === 'stop') result = await stopGovernanceController(options);
+  else result = await controllerStatus(options);
+  if (!options.json) {
+    process.stdout.write(`Marrow controller: ${result.active ? 'active' : result.state}.\n`);
+    if (result.started_at) process.stdout.write(`Started: ${result.started_at}\n`);
+    if (result.exact_fix) process.stdout.write(`Next: ${result.exact_fix}\n`);
+  }
+  return { ok: result.active || parsed.action === 'stop', controller: result };
 }
 
 async function gateOnly(parsed) {
@@ -1056,7 +1360,7 @@ function fleetPanel(snapshot) {
 const GENERIC_GOVERNED_COMMAND = 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run --agent <agent-id> --profile production --policy warn -- <harness-command>';
 
 function localSupportedHarnesses() {
-  return [
+  const harnesses = [
     { display_name: 'OpenAI Codex', client_label: 'codex', category: 'agent_harness', support_level: 'governed_runner', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run --agent codex-prod -- codex' },
     { display_name: 'Claude Code', client_label: 'claude-code', category: 'agent_harness', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/mcp setup' },
     { display_name: 'Cursor', client_label: 'cursor', category: 'ide_agent', support_level: 'native_mcp_or_sdk', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/mcp setup' },
@@ -1077,6 +1381,63 @@ function localSupportedHarnesses() {
     { display_name: 'CI scripts and deploy runners', client_label: 'ci', category: 'ci_runner', support_level: 'governed_runner', install_command: 'MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run --agent ci-release --profile production --policy enforce -- <ci-or-deploy-command>' },
     { display_name: 'Custom shell/API harness', client_label: 'custom', category: 'custom_runner', support_level: 'event_contract', install_command: 'POST /v1/agent/integrations/events with harness, event_type, agent_id, and action' },
   ];
+  return harnesses.map((harness) => {
+    const capability = HARNESS_CAPABILITY_REGISTRY.find((entry) => entry.client === harness.client_label)
+      || HARNESS_CAPABILITY_REGISTRY.find((entry) => entry.client === 'custom');
+    return { ...harness, capability_level: capability.capability_level };
+  });
+}
+
+function integrationCoverageMatrix() {
+  return HARNESS_CAPABILITY_REGISTRY.map((entry) => {
+    const native = entry.capability_level === 'native_hooks';
+    const wrapper = entry.capability_level === 'governed_wrapper';
+    const routed = entry.capability_level === 'mcp';
+    const sdk = entry.capability_level === 'sdk_passive_runtime';
+    return {
+      harness: entry.client,
+      capability_level: entry.capability_level,
+      install_surface: entry.install_surface,
+      pre_action: native
+        ? 'automatic_native_hook'
+        : wrapper
+          ? 'automatic_in_governed_runner'
+          : sdk
+            ? 'automatic_in_sdk_runtime'
+            : routed
+              ? 'mcp_routed'
+              : 'adapter_required',
+      action_result: native
+        ? 'automatic_native_hook'
+        : wrapper
+          ? 'automatic_in_governed_runner'
+          : sdk
+            ? 'automatic_in_sdk_runtime'
+            : routed
+              ? 'mcp_routed'
+              : 'adapter_required',
+      outcome_closure: wrapper || sdk
+        ? 'automatic_when_result_is_known'
+        : native
+          ? 'correlated_when_determinable'
+          : routed
+            ? 'mcp_routed'
+            : 'adapter_required',
+      proof_enforcement: native || wrapper || sdk
+        ? 'automatic_for_protected_actions'
+        : routed
+          ? 'explicit_or_governed_wrapper'
+          : 'adapter_required',
+      automatic_repair: native || routed || sdk || wrapper ? 'installer_managed_config_only' : 'adapter_owned',
+      limitation: native
+        ? 'A successful tool exit is not treated as a successful business outcome when the result cannot be proven.'
+        : routed
+          ? 'Only actions routed through the MCP client are visible automatically.'
+          : wrapper
+            ? 'Only commands launched through the governed wrapper receive full automatic coverage.'
+            : 'The harness must emit the documented lifecycle event contract.',
+    };
+  });
 }
 
 function detectHarnesses(cwd = process.cwd()) {
@@ -1209,16 +1570,22 @@ async function integrationOnly(parsed, name) {
 
 async function integrationsOnly(parsed) {
   const local = {
-    integration_registry_version: 'local.broad-harness-support-v2',
+    integration_registry_version: 'local.automatic-control-v3',
     first_class_addons: ['hermes', 'openclaw'].map((name) => localIntegrationManifest(name)),
     supported_harnesses: localSupportedHarnesses(),
+    integration_coverage: integrationCoverageMatrix(),
     exact_next_action: 'Pick the harness your team already uses. Use the install_command shown here, or send compact events to /v1/agent/integrations/events.',
   };
   let registry = local;
   let source = 'local';
   if (parsed.options.apiKey) {
     try {
-      registry = await requestJson(parsed.options, 'GET', '/v1/agent/integrations');
+      const remote = await requestJson(parsed.options, 'GET', '/v1/agent/integrations');
+      registry = {
+        ...local,
+        ...remote,
+        integration_coverage: local.integration_coverage,
+      };
       source = 'api';
     } catch (error) {
       registry = { ...local, api_warning: error instanceof Error ? error.message : String(error) };
@@ -1226,6 +1593,7 @@ async function integrationsOnly(parsed) {
   }
   if (parsed.options.json) return { ok: true, source, registry };
   const harnesses = Array.isArray(registry.supported_harnesses) ? registry.supported_harnesses : [];
+  const coverage = Array.isArray(registry.integration_coverage) ? registry.integration_coverage : [];
   process.stdout.write([
     'Marrow Harness Integrations',
     '',
@@ -1233,6 +1601,9 @@ async function integrationsOnly(parsed) {
     'Supported harnesses and model CLIs:',
     ...harnesses.map((harness) => `  - ${displayText(harness.display_name || harness.client_label || harness.integration || harness.title, 40)} [${displayText(harness.support_level || 'supported', 24)}]  ${displayText(harness.install_command || harness.install_commands?.[0] || '', 120)}`),
     '',
+    'Automatic lifecycle coverage:',
+    ...coverage.map((entry) => `  - ${displayText(entry.harness, 24)}: pre=${entry.pre_action}; result=${entry.action_result}; closure=${entry.outcome_closure}; proof=${entry.proof_enforcement}; repair=${entry.automatic_repair}`),
+    '',
     'First-class add-on guides: hermes, openclaw',
     `Next: ${displayText(registry.exact_next_action, 140)}`,
     registry.api_warning ? `API warning: ${displayText(registry.api_warning, 120)}` : '',
@@ -1859,6 +2230,11 @@ async function runCli(argv) {
   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 === 'permit') result = await permitOnly(parsed);
+  else if (parsed.command === 'verify-permit') result = await verifyPermitOnly(parsed);
+  else if (parsed.command === 'coverage') result = await coverageOnly(parsed);
+  else if (parsed.command === 'sidecar') result = await sidecarOnly(parsed);
+  else if (parsed.command === 'controller') result = await controllerOnly(parsed);
   else if (parsed.command === 'govern') {
     await runGovernInteractive(parsed.options);
     return;
@@ -1877,7 +2253,9 @@ async function runCli(argv) {
   else if (parsed.command === 'status') process.stdout.write(`${statusPanel(result)}\n`);
   else if (!['run', 'fleet', 'hermes', 'openclaw', 'integrations'].includes(parsed.command)) process.stdout.write('Marrow command completed.\n');
 
-  if (parsed.command === 'run' || result?.blocked) process.exitCode = result?.exitCode ?? (result?.ok === false ? 1 : 0);
+  if (parsed.command === 'run' || parsed.command === 'verify-permit' || result?.blocked) {
+    process.exitCode = result?.exitCode ?? (result?.ok === false ? 1 : 0);
+  }
 }
 
 module.exports = {
@@ -1890,6 +2268,7 @@ module.exports = {
   headers,
   inferType,
   inferSurfaces,
+  isRisky,
   commandForSelection,
   buildGovernState,
   detectProjectSignals,
@@ -1901,6 +2280,13 @@ module.exports = {
   renderGovernTui,
   canUseInteractive,
   runGoverned,
+  scopedExecutionEnv,
+  permitOnly,
+  verifyPermitOnly,
+  coverageOnly,
+  sidecarOnly,
+  controllerOnly,
+  actionBinding,
   gateOnly,
   proofOnly,
   statusOnly,
@@ -1916,6 +2302,7 @@ module.exports = {
   renderFleetTui,
   runFleetInteractive,
   localSupportedHarnesses,
+  integrationCoverageMatrix,
   localIntegrationManifest,
   renderIntegrationPanel,
   integrationOnly,