@getmarrow/install 0.1.36 → 0.1.37

package/README.md

@@ -74,9 +74,34 @@ npx -y @getmarrow/install@latest doctor
 npx -y @getmarrow/install@latest --repair
 ```
 
-`activate` reconciles Marrow-managed entries while retaining unrelated user hooks and configuration. Detection and notification are automatic; local changes remain explicit and subject to the operator's normal change policy.
+`activate` reconciles Marrow-managed entries while retaining unrelated user hooks and configuration. After that explicit activation, the local controller can restore drifted Marrow-managed hooks and configuration. Package upgrades, owner policy, credentials, and unrelated local files remain explicit and subject to the operator's normal change policy.
 
-## What's New in v0.1.36
+## Automatic Controller
+
+On Linux, successful install, repair, and activation starts a loopback-only controller that survives individual agent sessions. It keeps the signed action-permit broker available, checks installer-managed hooks every five minutes, safely restores missing managed entries, and reports an exact fix when repair is not safe. The API key remains process-only; private controller state is owner-only and contains no Marrow credential.
+
+```bash
+npx @getmarrow/install controller status
+npx @getmarrow/install controller ensure
+npx @getmarrow/install controller stop
+```
+
+Persistent controller lifecycle is currently Linux-only. On macOS or Windows, activation still installs and verifies the supported hooks without starting or signaling a background process; 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.37
+
+v0.1.37 adds the automatic local control lifecycle after explicit owner activation:
+
+- a project-and-agent-scoped loopback controller survives individual agent sessions;
+- installer-managed hooks are checked and safely restored without changing unrelated files;
+- the governed runner automatically classifies consequential commands and requires fresh signed permits for protected actions;
+- pre-action, execution, result, proof, and outcome receipts share stable correlation;
+- integration coverage states exactly what is native, MCP-routed, governed-wrapper controlled, or adapter-required;
+- in-session value messages use measured evidence only and report unavailable data instead of synthetic savings.
+
+It preserves the update and permit controls introduced in v0.1.36.
+
+## Previous: v0.1.36
 
 v0.1.36 combines guided, operator-controlled client updates with a signed permit boundary for protected actions. Installer status, activation reports, and the Fleet Operator expose request-specific update advisories with exact update and verification commands while keeping local mutation explicit:
 
@@ -200,6 +225,7 @@ npx @getmarrow/install permit --agent deploy-agent --type deploy --action "deplo
 MARROW_ACTION_PERMIT=... npx @getmarrow/install verify-permit --agent deploy-agent --type deploy --action "deploy production"
 npx @getmarrow/install coverage --agent deploy-agent
 npx @getmarrow/install sidecar --agent deploy-agent
+npx @getmarrow/install controller status
 npx @getmarrow/install status
 npx @getmarrow/install doctor
 npx @getmarrow/install --repair
@@ -225,6 +251,19 @@ The fleet view shows live agents, active workflows, agent disagreements and thei
 
 These are integration surfaces for one Marrow product, not separate products.
 
+## Exact Integration Coverage
+
+Run `npx @getmarrow/install integrations --json` for the machine-readable matrix. The table below intentionally distinguishes full automatic interception from MCP-routed, wrapper-bounded, and adapter-required coverage.
+
+| Harnesses | Pre-action | Result | Outcome closure | Proof enforcement | Safe repair |
+| --- | --- | --- | --- | --- | --- |
+| Claude Code | Automatic native hook | Automatic native hook | Correlated when determinable | Automatic for protected actions | Managed config after activation |
+| Cursor, Composer, Cline, Windsurf | MCP-routed | MCP-routed | MCP-routed | Explicit or governed runner | Managed config after activation |
+| Codex, OpenCode, Gemini, Grok, DeepSeek, Qwen, Kimi, MiniMax, GLM | Automatic inside governed runner | Automatic inside governed runner | Automatic when result is known | Automatic for protected actions | Managed config after activation |
+| Hermes, OpenClaw, custom harnesses | Adapter required | Adapter required | Adapter required | Adapter required | 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.
+
 ## Always-On Lifecycle
 
 Supported integrations capture a compact lifecycle without storing raw prompts, completions, command output, tool output, or credentials. Marrow recognizes prompt, goal, pre-action, tool/command result, verification evidence, workflow/session, subagent, handoff, proof-pack, and outcome events.

package/bin/marrow-install.js

@@ -4,7 +4,7 @@ const installer = require('../src/installer');
 const governedRunner = require('../src/governed-runner');
 
 const argv = process.argv.slice(2);
-const governedCommands = new Set(['run', 'gate', 'proof', 'status', 'govern', 'fleet', 'hermes', 'openclaw', 'integrations', 'permit', 'verify-permit', 'coverage', 'sidecar']);
+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;
 
 runCli(argv).catch((error) => {

package/package.json

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

package/src/controller-manager.js

@@ -0,0 +1,449 @@
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const START_TIMEOUT_MS = 5_000;
+const STOP_TIMEOUT_MS = 3_000;
+const HEALTH_TIMEOUT_MS = 1_000;
+const MAX_STATE_BYTES = 8 * 1024;
+const LIFECYCLE_LOCK_STALE_MS = 30_000;
+
+function controllerIdentity(options = {}) {
+  const root = path.resolve(options.root || process.cwd());
+  const agentId = String(options.agentId || process.env.MARROW_FLEET_AGENT_ID || process.env.MARROW_AGENT_ID || 'agent').trim() || 'agent';
+  return crypto.createHash('sha256').update(`${root}\0${agentId}`).digest('hex').slice(0, 24);
+}
+
+function controllerDirectory(options = {}) {
+  return process.env.MARROW_SIDECAR_STATE_DIR
+    || path.join(os.homedir(), '.marrow', 'controllers', controllerIdentity(options));
+}
+
+function stateFile(options = {}) {
+  return path.join(controllerDirectory(options), 'active.json');
+}
+
+function lifecycleLockFile(options = {}) {
+  return path.join(controllerDirectory(options), 'lifecycle.lock');
+}
+
+function currentUid() {
+  return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+
+function assertPrivatePath(filePath, kind) {
+  const stat = fs.lstatSync(filePath);
+  const uid = currentUid();
+  if (stat.isSymbolicLink()) throw new Error(`Controller ${kind} cannot be a symlink.`);
+  if (kind === 'directory' ? !stat.isDirectory() : !stat.isFile()) {
+    throw new Error(`Controller ${kind} has an invalid file type.`);
+  }
+  if (uid !== null && stat.uid !== uid) throw new Error(`Controller ${kind} must be owned by the current user.`);
+  const forbidden = kind === 'directory' ? 0o077 : 0o077;
+  if ((stat.mode & forbidden) !== 0) throw new Error(`Controller ${kind} permissions are too broad.`);
+  return stat;
+}
+
+function ensurePrivateDirectory(options = {}) {
+  const directory = path.resolve(controllerDirectory(options));
+  const parsed = path.parse(directory);
+  let current = parsed.root;
+  for (const segment of directory.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      fs.mkdirSync(current, { mode: 0o700 });
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink() || !stat.isDirectory() || fs.realpathSync(current) !== current) {
+      throw new Error('Controller state directory cannot contain symlinked path components.');
+    }
+    if ((stat.mode & 0o022) !== 0 && (stat.mode & 0o1000) === 0) {
+      throw new Error('Controller state directory cannot be nested under a non-sticky writable ancestor.');
+    }
+  }
+  fs.chmodSync(directory, 0o700);
+  assertPrivatePath(directory, 'directory');
+  return directory;
+}
+
+function readState(options = {}) {
+  const filePath = stateFile(options);
+  if (!fs.existsSync(filePath)) return null;
+  const stat = assertPrivatePath(filePath, 'state file');
+  if (stat.size > MAX_STATE_BYTES) throw new Error('Controller state file is oversized.');
+  const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Controller state is invalid.');
+  if (!Number.isInteger(value.pid) || value.pid <= 1) throw new Error('Controller state PID is invalid.');
+  if (!Number.isInteger(value.port) || value.port < 1 || value.port > 65535) throw new Error('Controller state port is invalid.');
+  if (value.host !== '127.0.0.1') throw new Error('Controller state is not loopback-bound.');
+  if (typeof value.token !== 'string' || !/^[a-f0-9]{64}$/.test(value.token)) throw new Error('Controller state token is invalid.');
+  if (typeof value.instance_id !== 'string' || !/^sidecar-[0-9a-f-]{36}$/.test(value.instance_id)) throw new Error('Controller instance identity is invalid.');
+  if (!Number.isFinite(Date.parse(value.started_at))) throw new Error('Controller start timestamp is invalid.');
+  return value;
+}
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function controllerSupportedPlatform(platform = process.platform) {
+  return platform === 'linux';
+}
+
+function isExpectedControllerProcess(pid, platform = process.platform) {
+  if (!controllerSupportedPlatform(platform) || !Number.isInteger(pid) || pid <= 1) return false;
+  try {
+    const args = fs.readFileSync(`/proc/${pid}/cmdline`).toString('utf8').split('\0').filter(Boolean);
+    if (args.length < 3 || args[2] !== 'sidecar') return false;
+    return fs.realpathSync(args[1]) === fs.realpathSync(require.resolve('../bin/marrow-install.js'));
+  } catch {
+    return false;
+  }
+}
+
+async function controllerStatus(options = {}) {
+  if (!controllerSupportedPlatform(options.platform)) {
+    return {
+      active: false,
+      state: 'unsupported_platform',
+      started_at: null,
+      instance_id: null,
+      exact_fix: 'Persistent controller lifecycle is currently supported on Linux. Use --no-controller and run npx @getmarrow/install sidecar under an owner-managed service.',
+    };
+  }
+  let state;
+  try {
+    state = readState(options);
+  } catch (error) {
+    return {
+      active: false,
+      state: 'invalid_state',
+      started_at: null,
+      instance_id: null,
+      exact_fix: 'Run npx @getmarrow/install controller stop, then npx @getmarrow/install controller ensure.',
+      error: error instanceof Error ? error.message : 'Controller state is invalid.',
+    };
+  }
+  if (!state) {
+    return {
+      active: false,
+      state: 'stopped',
+      started_at: null,
+      instance_id: null,
+      exact_fix: 'Run npx @getmarrow/install controller ensure.',
+    };
+  }
+  if (!pidAlive(state.pid)) {
+    return {
+      active: false,
+      state: 'stale',
+      started_at: state.started_at,
+      instance_id: state.instance_id,
+      exact_fix: 'Run npx @getmarrow/install controller ensure.',
+    };
+  }
+  if (!isExpectedControllerProcess(state.pid, options.platform)) {
+    return {
+      active: false,
+      state: 'identity_mismatch',
+      started_at: state.started_at,
+      instance_id: state.instance_id,
+      exact_fix: 'Inspect the recorded process and controller state before retrying. Marrow will not signal an unverified PID.',
+    };
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), HEALTH_TIMEOUT_MS);
+  timeout.unref?.();
+  try {
+    const response = await fetch(`http://127.0.0.1:${state.port}/health`, {
+      headers: { Authorization: `Bearer ${state.token}` },
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      return {
+        active: false,
+        state: 'identity_mismatch',
+        started_at: state.started_at,
+        instance_id: state.instance_id,
+        exact_fix: 'Inspect the authenticated controller endpoint and private state before retrying. Marrow will not signal either process.',
+      };
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      return {
+        active: false,
+        state: 'identity_mismatch',
+        started_at: state.started_at,
+        instance_id: state.instance_id,
+        exact_fix: 'Inspect the authenticated controller endpoint and private state before retrying. Marrow will not signal either process.',
+      };
+    }
+    if (body?.ok !== true || body?.instance_id !== state.instance_id || body?.pid !== state.pid) {
+      return {
+        active: false,
+        state: 'identity_mismatch',
+        started_at: state.started_at,
+        instance_id: state.instance_id,
+        exact_fix: 'Inspect the authenticated controller endpoint and private state before retrying. Marrow will not signal either process.',
+      };
+    }
+    const maintenance = body.maintenance && typeof body.maintenance === 'object'
+      ? body.maintenance
+      : null;
+    return {
+      active: true,
+      state: 'active',
+      started_at: state.started_at,
+      instance_id: state.instance_id,
+      maintenance,
+      exact_fix: maintenance?.exact_fix || null,
+    };
+  } catch {
+    return {
+      active: false,
+      state: 'unreachable',
+      started_at: state.started_at,
+      instance_id: state.instance_id,
+      exact_fix: 'Run npx @getmarrow/install controller stop, then npx @getmarrow/install controller ensure.',
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function cleanControllerEnv(options) {
+  const keep = [
+    'HOME', 'USER', 'LOGNAME', 'PATH', 'LANG', 'LC_ALL', 'TMPDIR', 'TEMP', 'TMP',
+    'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR',
+  ];
+  const env = {};
+  for (const name of keep) {
+    if (process.env[name]) env[name] = process.env[name];
+  }
+  env.MARROW_API_KEY = options.apiKey;
+  env.MARROW_BASE_URL = options.baseUrl;
+  env.MARROW_FLEET_AGENT_ID = options.agentId;
+  env.MARROW_AGENT_ID = options.agentId;
+  env.MARROW_CLIENT = options.client;
+  env.MARROW_GOVERN_PROFILE = options.profile;
+  env.MARROW_GOVERN_POLICY = options.policy;
+  env.MARROW_CONTROLLER_PROJECT_ROOT = path.resolve(options.root || process.cwd());
+  env.MARROW_CONTROLLER_MANAGED_MODE = options.mode || 'auto';
+  env.MARROW_SIDECAR_STATE_DIR = controllerDirectory(options);
+  return env;
+}
+
+async function waitFor(predicate, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  do {
+    const result = await predicate();
+    if (result) return result;
+    await new Promise((resolve) => setTimeout(resolve, 75));
+  } while (Date.now() < deadline);
+  return null;
+}
+
+function tryAcquireLifecycleLock(options = {}) {
+  const filePath = lifecycleLockFile(options);
+  const nonce = crypto.randomBytes(16).toString('hex');
+  let descriptor;
+  let created = false;
+  try {
+    descriptor = fs.openSync(filePath, 'wx', 0o600);
+    created = true;
+    fs.writeFileSync(descriptor, JSON.stringify({
+      pid: process.pid,
+      nonce,
+      created_at: new Date().toISOString(),
+    }) + '\n', 'utf8');
+    fs.fsyncSync(descriptor);
+    fs.chmodSync(filePath, 0o600);
+    return { descriptor, filePath, nonce };
+  } catch (error) {
+    if (descriptor !== undefined) {
+      try { fs.closeSync(descriptor); } catch {}
+    }
+    if (created) {
+      try { fs.unlinkSync(filePath); } catch {}
+    }
+    if (error?.code !== 'EEXIST') throw error;
+    const stat = assertPrivatePath(filePath, 'lifecycle lock');
+    if (stat.size > MAX_STATE_BYTES) throw new Error('Controller lifecycle lock is oversized.');
+    let value;
+    try {
+      value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch {
+      throw new Error('Controller lifecycle lock is invalid.');
+    }
+    const stale = Date.now() - stat.mtimeMs > LIFECYCLE_LOCK_STALE_MS;
+    if (stale && Number.isInteger(value?.pid) && !pidAlive(value.pid)) {
+      fs.unlinkSync(filePath);
+      return null;
+    }
+    return false;
+  }
+}
+
+async function acquireLifecycleLock(options = {}) {
+  const deadline = Date.now() + START_TIMEOUT_MS;
+  do {
+    const lock = tryAcquireLifecycleLock(options);
+    if (lock) return lock;
+    await new Promise((resolve) => setTimeout(resolve, 75));
+  } while (Date.now() < deadline);
+  throw new Error('Another Marrow controller lifecycle operation is still in progress.');
+}
+
+function releaseLifecycleLock(lock) {
+  if (!lock) return;
+  try { fs.closeSync(lock.descriptor); } catch {}
+  try {
+    const stat = assertPrivatePath(lock.filePath, 'lifecycle lock');
+    if (stat.size > MAX_STATE_BYTES) return;
+    const value = JSON.parse(fs.readFileSync(lock.filePath, 'utf8'));
+    if (value?.nonce === lock.nonce) fs.unlinkSync(lock.filePath);
+  } catch {}
+}
+
+function removeStaleState(options = {}) {
+  const filePath = stateFile(options);
+  if (!fs.existsSync(filePath)) return;
+  assertPrivatePath(filePath, 'state file');
+  fs.unlinkSync(filePath);
+}
+
+function removeInvalidState(options = {}) {
+  const filePath = stateFile(options);
+  if (!fs.existsSync(filePath)) return false;
+  assertPrivatePath(filePath, 'state file');
+  fs.unlinkSync(filePath);
+  return true;
+}
+
+async function stopRecordedController(state, options = {}) {
+  if (!pidAlive(state.pid)) return;
+  if (!isExpectedControllerProcess(state.pid, options.platform)) {
+    throw new Error('Refusing to terminate an unreachable process that cannot be verified as the Marrow controller.');
+  }
+  process.kill(state.pid, 'SIGTERM');
+  const stopped = await waitFor(async () => pidAlive(state.pid) ? null : true, STOP_TIMEOUT_MS);
+  if (!stopped) throw new Error('Marrow controller did not stop within the shutdown window.');
+}
+
+async function startGovernanceController(options) {
+  if (!controllerSupportedPlatform(options.platform)) {
+    throw new Error('Persistent controller lifecycle is currently supported on Linux. Use --no-controller and run the sidecar under an owner-managed service.');
+  }
+  if (!options.apiKey) throw new Error('MARROW_API_KEY is required to start the Marrow controller.');
+  const directory = ensurePrivateDirectory(options);
+  const lock = await acquireLifecycleLock(options);
+  try {
+    const current = await controllerStatus(options);
+    if (current.active) return { ...current, changed: false };
+    if (current.state === 'stale') removeStaleState(options);
+    if (current.state === 'unreachable') {
+      const prior = readState(options);
+      await stopRecordedController(prior, options);
+      removeStaleState(options);
+    }
+    if (current.state === 'identity_mismatch') {
+      throw new Error('Controller process identity is ambiguous; refusing automatic replacement.');
+    }
+    if (current.state === 'invalid_state') throw new Error(current.error || 'Controller state is invalid.');
+
+    const logPath = path.join(directory, 'controller.log');
+    if (fs.existsSync(logPath)) assertPrivatePath(logPath, 'log file');
+    const logFd = fs.openSync(logPath, 'a', 0o600);
+    fs.chmodSync(logPath, 0o600);
+    const binPath = require.resolve('../bin/marrow-install.js');
+    const args = [
+      binPath,
+      'sidecar',
+      '--agent', options.agentId,
+      '--client', options.client,
+      '--profile', options.profile,
+      '--policy', options.policy,
+    ];
+    let child;
+    try {
+      child = spawn(process.execPath, args, {
+        detached: true,
+        env: cleanControllerEnv(options),
+        stdio: ['ignore', logFd, logFd],
+      });
+      child.unref();
+    } finally {
+      fs.closeSync(logFd);
+    }
+
+    const active = await waitFor(async () => {
+      const status = await controllerStatus(options);
+      return status.active ? status : null;
+    }, START_TIMEOUT_MS);
+    if (!active) {
+      if (child?.pid && pidAlive(child.pid)) {
+        try { process.kill(child.pid, 'SIGTERM'); } catch {}
+      }
+      throw new Error('Marrow controller did not become healthy within the startup window.');
+    }
+    return { ...active, changed: true };
+  } finally {
+    releaseLifecycleLock(lock);
+  }
+}
+
+async function stopGovernanceController(options = {}) {
+  if (!controllerSupportedPlatform(options.platform)) {
+    throw new Error('Persistent controller lifecycle is currently supported on Linux. No process was signaled.');
+  }
+  ensurePrivateDirectory(options);
+  const lock = await acquireLifecycleLock(options);
+  try {
+    let state;
+    try {
+      state = readState(options);
+    } catch {
+      const changed = removeInvalidState(options);
+      return { active: false, state: 'stopped', changed, exact_fix: null };
+    }
+    if (!state) return { active: false, state: 'stopped', changed: false, exact_fix: null };
+    const current = await controllerStatus(options);
+    if (current.state === 'identity_mismatch') {
+      throw new Error('Refusing to stop a controller whose PID is not bound to its authenticated endpoint.');
+    }
+    if (current.active || current.state === 'unreachable') {
+      await stopRecordedController(state, options);
+    }
+    removeStaleState(options);
+    return { active: false, state: 'stopped', changed: true, exact_fix: null };
+  } finally {
+    releaseLifecycleLock(lock);
+  }
+}
+
+async function ensureGovernanceController(options) {
+  const current = await controllerStatus(options);
+  return current.active ? { ...current, changed: false } : startGovernanceController(options);
+}
+
+module.exports = {
+  controllerDirectory,
+  controllerIdentity,
+  controllerSupportedPlatform,
+  controllerStatus,
+  ensureGovernanceController,
+  readState,
+  startGovernanceController,
+  stopGovernanceController,
+};

package/src/governance-sidecar.js

@@ -29,6 +29,9 @@ function createPrivateDirectoryWithoutSymlinks(directory) {
     if (stat.isSymbolicLink() || !stat.isDirectory() || fs.realpathSync(current) !== current) {
       throw new Error('Sidecar state directory cannot contain symlinked path components.');
     }
+    if ((stat.mode & 0o022) !== 0 && (stat.mode & 0o1000) === 0) {
+      throw new Error('Sidecar state directory cannot be nested under a non-sticky writable ancestor.');
+    }
   }
   return resolved;
 }
@@ -90,12 +93,14 @@ function writePrivateJsonAtomic(filePath, value) {
   }
 }
 
-function unlinkPrivateStateFile(filePath) {
+function unlinkPrivateStateFile(filePath, expectedInstanceId) {
   try {
     const stat = fs.lstatSync(filePath);
     const uid = currentUid();
     if (!stat.isSymbolicLink() && stat.isFile() && (uid === null || stat.uid === uid)) {
-      fs.unlinkSync(filePath);
+      const raw = stat.size <= 8 * 1024 ? fs.readFileSync(filePath, 'utf8') : '';
+      const current = raw ? JSON.parse(raw) : null;
+      if (current?.instance_id === expectedInstanceId) fs.unlinkSync(filePath);
     }
   } catch {}
 }
@@ -131,6 +136,12 @@ async function startGovernanceSidecar(options, handlers) {
   const instanceId = `sidecar-${crypto.randomUUID()}`;
   const startedAt = new Date().toISOString();
   let latestCoverage = null;
+  let latestMaintenance = {
+    state: handlers.maintain ? 'pending' : 'unavailable',
+    checked_at: null,
+    repaired: [],
+    exact_fix: handlers.maintain ? null : 'Run npx @getmarrow/install --repair in the managed project.',
+  };
 
   const server = http.createServer(async (req, res) => {
     try {
@@ -142,7 +153,13 @@ async function startGovernanceSidecar(options, handlers) {
       }
       const url = new URL(req.url || '/', 'http://127.0.0.1');
       if (req.method === 'GET' && url.pathname === '/health') {
-        return json(res, 200, { ok: true, instance_id: instanceId, started_at: startedAt });
+        return json(res, 200, {
+          ok: true,
+          instance_id: instanceId,
+          pid: process.pid,
+          started_at: startedAt,
+          maintenance: latestMaintenance,
+        });
       }
       if (req.method === 'GET' && url.pathname === '/coverage') {
         latestCoverage = await handlers.coverage();
@@ -184,6 +201,18 @@ async function startGovernanceSidecar(options, handlers) {
   }
 
   const heartbeat = async () => {
+    if (handlers.maintain) {
+      try {
+        latestMaintenance = await handlers.maintain();
+      } catch {
+        latestMaintenance = {
+          state: 'attention_required',
+          checked_at: new Date().toISOString(),
+          repaired: [],
+          exact_fix: 'Run npx @getmarrow/install --repair in the managed project.',
+        };
+      }
+    }
     try {
       latestCoverage = await handlers.heartbeat({ sidecarInstanceId: instanceId });
     } catch {
@@ -199,7 +228,7 @@ async function startGovernanceSidecar(options, handlers) {
     if (closed) return;
     closed = true;
     clearInterval(timer);
-    unlinkPrivateStateFile(stateFile);
+    unlinkPrivateStateFile(stateFile, instanceId);
     process.off('SIGINT', close);
     process.off('SIGTERM', close);
     server.close();

package/src/governed-runner.js

@@ -14,6 +14,18 @@ const {
   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;
@@ -100,6 +112,8 @@ Commands:
   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
@@ -431,6 +445,16 @@ function parseArgs(argv) {
     return { command, options };
   }
 
+  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' };
@@ -687,13 +711,18 @@ async function runGoverned(parsed) {
   let decision = null;
   let decisionId = '';
   let actionPermit = null;
-  let permitEnforcementStarted = false;
   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 {
@@ -710,38 +739,37 @@ async function runGoverned(parsed) {
     const target = options.target || commandText;
     const think = await createDecision(options, action, type, target, surfaces);
     decisionId = think.decision_id || think.id || think.decision?.id || '';
-    permitEnforcementStarted = true;
-    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.');
+    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;
     }
-    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) {
-    const protectedAction = risky
-      || decision?.required === true
-      || decision?.riskLevel === 'high'
-      || decision?.riskLevel === 'critical';
-    const canDegrade = !permitEnforcementStarted
-      && !protectedAction
+    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 {
@@ -757,7 +785,7 @@ async function runGoverned(parsed) {
     }
   }
 
-  const childEnv = scopedExecutionEnv(actionPermit);
+  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 });
@@ -796,6 +824,7 @@ async function runGoverned(parsed) {
     action,
     type,
     risky,
+    degraded,
     decision,
     decision_id: decisionId,
     outcome_committed: Boolean(commit),
@@ -853,18 +882,54 @@ async function coverageOnly(parsed) {
 
 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) {
   const { options } = parsed;
   const action = redact(options.action);
@@ -1295,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' },
@@ -1316,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()) {
@@ -1448,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) };
@@ -1465,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',
     '',
@@ -1472,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)}` : '',
@@ -2102,6 +2234,7 @@ async function runCli(argv) {
   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;
@@ -2152,6 +2285,7 @@ module.exports = {
   verifyPermitOnly,
   coverageOnly,
   sidecarOnly,
+  controllerOnly,
   actionBinding,
   gateOnly,
   proofOnly,
@@ -2168,6 +2302,7 @@ module.exports = {
   renderFleetTui,
   runFleetInteractive,
   localSupportedHarnesses,
+  integrationCoverageMatrix,
   localIntegrationManifest,
   renderIntegrationPanel,
   integrationOnly,

package/src/installer.js

@@ -3,13 +3,14 @@ const path = require('node:path');
 const os = require('node:os');
 const crypto = require('node:crypto');
 const { version: INSTALLER_ADAPTER_VERSION } = require('../package.json');
+const { controllerStatus, controllerSupportedPlatform, ensureGovernanceController } = require('./controller-manager');
 
 const DEFAULT_BASE_URL = 'https://api.getmarrow.ai';
 const MARROW_BLOCK_START = '<!-- marrow:passive-start -->';
 const MARROW_BLOCK_END = '<!-- marrow:passive-end -->';
-const MCP_ADAPTER_VERSION = '3.9.52';
-const SDK_ADAPTER_VERSION = '3.7.51';
-const SDK_ADAPTER_INTEGRITY = 'sha512-0l4UOeJLZ8izIoci4TRy22svKm3xvoyyAbU16aB3vnqxvsrdv3TDaz2EqXpo0vz62IEMlx/F+IoiQ9t9xKzdFA==';
+const MCP_ADAPTER_VERSION = '3.9.53';
+const SDK_ADAPTER_VERSION = '3.7.52';
+const SDK_ADAPTER_INTEGRITY = 'sha512-dMo5rMXP5sFTRsiRI+Oe3SOWgSsi8TTt9VrYL9gC71EQFN2UTtuH914CkYEpcS627sb02jXrUDiXxznX/2fWgA==';
 const SDK_ADAPTER_TARBALL = `https://registry.npmjs.org/@getmarrow/sdk/-/sdk-${SDK_ADAPTER_VERSION}.tgz`;
 const MCP_PACKAGE_SPEC = `@getmarrow/mcp@${MCP_ADAPTER_VERSION}`;
 const MCP_CONTEXT_HOOK_COMMAND = `npx -y ${MCP_PACKAGE_SPEC} context-hook`;
@@ -18,7 +19,7 @@ const MCP_ACTION_RESULT_HOOK_COMMAND = `npx -y ${MCP_PACKAGE_SPEC} hook`;
 const MCP_SESSION_END_HOOK_COMMAND = `npx -y ${MCP_PACKAGE_SPEC} session-hook`;
 const NATIVE_HOOK_MATCHER = 'Bash|Edit|Write|MultiEdit|mcp__(?!marrow_).*';
 const NATIVE_EXPECTED_HOOKS = ['prompt', 'pre_action', 'action_result', 'session_end'];
-const SOURCE_CLIENTS = new Set(['claude-code', 'cursor', 'composer', 'windsurf', 'openclaw', 'codex', 'gemini', 'grok', 'deepseek', 'qwen', 'kimi', 'minimax', 'cline', 'opencode', 'hermes', 'glm', 'custom', 'unknown']);
+const SOURCE_CLIENTS = new Set(['claude-code', 'cursor', 'composer', 'windsurf', 'openclaw', 'codex', 'gemini', 'grok', 'deepseek', 'qwen', 'kimi', 'minimax', 'cline', 'opencode', 'hermes', 'glm', 'mcp', 'ci', 'custom', 'unknown']);
 const HARNESS_CAPABILITY_REGISTRY = Object.freeze([
   { client: 'claude-code', capability_level: 'native_hooks', automatic: ['prompt', 'pre_action', 'action_result', 'session_end'], install_surface: 'mcp' },
   { client: 'cursor', capability_level: 'mcp', automatic: ['mcp_tool_calls'], install_surface: 'mcp' },
@@ -36,6 +37,8 @@ const HARNESS_CAPABILITY_REGISTRY = Object.freeze([
   { client: 'kimi', capability_level: 'governed_wrapper', automatic: ['pre_action', 'action_result', 'outcome_closure'], install_surface: 'runner' },
   { client: 'minimax', capability_level: 'governed_wrapper', automatic: ['pre_action', 'action_result', 'outcome_closure'], install_surface: 'runner' },
   { client: 'glm', capability_level: 'governed_wrapper', automatic: ['pre_action', 'action_result', 'outcome_closure'], install_surface: 'runner' },
+  { client: 'mcp', capability_level: 'mcp', automatic: ['mcp_tool_calls'], install_surface: 'mcp' },
+  { client: 'ci', capability_level: 'governed_wrapper', automatic: ['pre_action', 'action_result', 'outcome_closure'], install_surface: 'runner' },
   { client: 'custom', capability_level: 'event_contract', automatic: [], install_surface: 'event_contract' },
 ]);
 
@@ -64,6 +67,9 @@ function sourceClient() {
     hermes: 'hermes',
     'hermes-agent': 'hermes',
     glm: 'glm',
+    mcp: 'mcp',
+    ci: 'ci',
+    'github-actions': 'ci',
   };
   return aliases[raw] || (SOURCE_CLIENTS.has(raw) ? raw : 'custom');
 }
@@ -83,6 +89,7 @@ function parseArgs(argv) {
     selfTestExplicitlyDisabled: false,
     json: false,
     activate: false,
+    controller: true,
   };
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -104,6 +111,7 @@ function parseArgs(argv) {
       options.selfTest = false;
       options.selfTestExplicitlyDisabled = true;
     }
+    else if (arg === '--no-controller') options.controller = false;
     else if (arg === '--self-test') options.selfTest = true;
     else if (arg === '--cwd') options.cwd = path.resolve(argv[++i] || options.cwd);
     else if (arg === '--mode') options.mode = argv[++i] || options.mode;
@@ -157,6 +165,7 @@ Options:
   --key <key>        Marrow API key for self-test. Prefer MARROW_API_KEY because CLI args can appear in process listings.
   --base-url <url>   Marrow API base URL
   --agent-id <id>    Agent/fleet id for self-test headers
+  --no-controller    Do not start the local background controller during install/repair
   --no-self-test     Skip API smoke/self-test
 `;
 }
@@ -1263,8 +1272,13 @@ async function runSelfTest(options) {
       avoided_mistakes: performance.avoided_mistakes ?? performance.avoided_repeated_mistakes ?? 0,
       reused_winning_decisions: performance.reused_winning_decisions ?? 0,
       prevented_bad_actions: performance.prevented_bad_actions ?? 0,
-      estimated_tokens_saved: performance.token_time_saved_estimate?.estimated_tokens_saved ?? 0,
-      estimated_minutes_saved: performance.token_time_saved_estimate?.estimated_minutes_saved ?? 0,
+      estimated_tokens_saved: tokenValueProof?.savings?.estimated_tokens_saved ?? null,
+      estimated_minutes_saved: tokenValueProof?.savings?.estimated_minutes_saved ?? null,
+      token_savings_available: Number(tokenValueProof?.observed?.model_calls || 0) > 0
+        && Number(tokenValueProof?.savings?.estimated_tokens_saved || 0) > 0,
+      token_savings_source: 'agent_model_usage_events',
+      token_savings_method: tokenValueProof?.savings?.method || 'warming_up',
+      token_savings_confidence: tokenValueProof?.savings?.confidence || 'none',
       reliability_score: performance.agent_reliability_score ?? null,
     } : null,
   };
@@ -1287,10 +1301,22 @@ function buildTokenValueProof(valueProof = {}) {
   return modelUsage;
 }
 
+function tokenValueProofLine(tokenValueProof) {
+  const calls = Number(tokenValueProof?.observed?.model_calls || 0);
+  const saved = Number(tokenValueProof?.savings?.estimated_tokens_saved || 0);
+  if (calls > 0 && saved > 0) {
+    const method = tokenValueProof.savings?.method || 'unspecified';
+    const confidence = tokenValueProof.savings?.confidence || 'unknown';
+    return `Marrow observed ${calls} model call${calls === 1 ? '' : 's'} and estimates ~${saved} tokens saved (${method}, ${confidence} confidence)`;
+  }
+  return tokenValueProof?.proof_line || null;
+}
+
 function buildInstallValueMoment(firstValueSignal = {}, status = {}, runtime = {}, performance = {}, firstValue = {}, tokenValueProof = null) {
   if (firstValue && firstValue.ok !== false && firstValue.first_value) {
     const proof = Array.isArray(firstValue.first_value.proof) ? [...firstValue.first_value.proof] : [];
-    if (tokenValueProof?.proof_line && !proof.includes(tokenValueProof.proof_line)) proof.push(tokenValueProof.proof_line);
+    const tokenProofLine = tokenValueProofLine(tokenValueProof);
+    if (tokenProofLine && !proof.includes(tokenProofLine)) proof.push(tokenProofLine);
     return {
       headline: firstValue.headline || firstValue.first_value.headline || 'Your agent is no longer starting from zero.',
       proof,
@@ -1315,7 +1341,7 @@ function buildInstallValueMoment(firstValueSignal = {}, status = {}, runtime = {
       'Closed the outcome successfully',
       'Runtime gate is ' + (firstValueSignal.active ? 'active' : 'installed'),
       runtimeLesson ? 'Future risky work now gets a pre-action brief' : 'Future risky work now gets checked before action',
-      tokenValueProof?.proof_line || 'Token usage proof is active and warming up after the first model call',
+      tokenValueProofLine(tokenValueProof) || 'Token usage proof is active and warming up after the first model call',
     ],
     fleet_signal: hasFleetSignal
       ? 'Marrow already found signal: ' + proof.join('; ') + '.'
@@ -1334,9 +1360,8 @@ function buildFirstValueSignal(status, runtime, performance, firstValue = {}, to
     if (Number(proof.avoided_mistakes || 0) > 0) proofBits.push(`${proof.avoided_mistakes} avoided mistake(s)`);
     if (Number(proof.reused_winning_decisions || 0) > 0) proofBits.push(`${proof.reused_winning_decisions} reused winning decision(s)`);
     if (Number(proof.prevented_bad_actions || 0) > 0) proofBits.push(`${proof.prevented_bad_actions} prevented risky action(s)`);
-    if (Number(proof.estimated_tokens_saved || 0) > 0) proofBits.push(`~${proof.estimated_tokens_saved} tokens saved`);
-    if (Number(tokenValueProof?.savings?.estimated_tokens_saved || 0) > 0) proofBits.push(`~${tokenValueProof.savings.estimated_tokens_saved} measured model tokens saved`);
-    else if (tokenValueProof?.proof_line) proofBits.push(tokenValueProof.proof_line);
+    const tokenProofLine = tokenValueProofLine(tokenValueProof);
+    if (tokenProofLine) proofBits.push(tokenProofLine);
     return {
       active: Boolean(firstValue.active),
       headline: `Marrow active: ${(capture.surfaces || ['decisions']).join(', ')} captured.`,
@@ -1362,10 +1387,8 @@ function buildFirstValueSignal(status, runtime, performance, firstValue = {}, to
   if (Number(proof.avoided_mistakes || proof.avoided_repeated_mistakes || 0) > 0) proofBits.push(`${proof.avoided_mistakes || proof.avoided_repeated_mistakes} avoided mistake(s)`);
   if (Number(proof.reused_winning_decisions || 0) > 0) proofBits.push(`${proof.reused_winning_decisions} reused winning decision(s)`);
   if (Number(proof.prevented_bad_actions || 0) > 0) proofBits.push(`${proof.prevented_bad_actions} prevented risky action(s)`);
-  const tokens = proof.token_time_saved_estimate?.estimated_tokens_saved || 0;
-  if (tokens > 0) proofBits.push(`~${tokens} tokens saved`);
-  if (Number(tokenValueProof?.savings?.estimated_tokens_saved || 0) > 0) proofBits.push(`~${tokenValueProof.savings.estimated_tokens_saved} measured model tokens saved`);
-  else if (tokenValueProof?.proof_line) proofBits.push(tokenValueProof.proof_line);
+  const tokenProofLine = tokenValueProofLine(tokenValueProof);
+  if (tokenProofLine) proofBits.push(tokenProofLine);
 
   const firstLesson = runtime.before_you_act
     || runtime.before_you_act_injection?.message
@@ -1495,6 +1518,11 @@ function printReport(report) {
     if (report.sdkDependency.warning) process.stdout.write(`- warning: ${report.sdkDependency.warning}\n`);
   }
 
+  process.stdout.write('\nAutomatic controller:\n');
+  process.stdout.write(`- state: ${report.controller?.active ? 'active' : report.controller?.state || 'unavailable'}\n`);
+  if (report.controller?.started_at) process.stdout.write(`- started: ${report.controller.started_at}\n`);
+  if (report.controller?.exact_fix) process.stdout.write(`- exact fix: ${report.controller.exact_fix}\n`);
+
   if (report.writeMode === 'doctor') {
     process.stdout.write('\nDoctor:\n');
     process.stdout.write(`- Marrow active: ${report.doctor.active ? 'yes' : 'no'}\n`);
@@ -1573,6 +1601,43 @@ async function install(options) {
   }
   const changedConfig = changes.some((change) => change.applied) || configRepairs.some((repair) => repair.changed);
   const selfTestPassed = Boolean(!selfTest.skipped && selfTest.active && !selfTest.error);
+  const controllerPlatform = options.controllerPlatform || process.platform;
+  let controller = await controllerStatus({
+    root: detection.root,
+    agentId: options.agentId,
+    platform: controllerPlatform,
+  });
+  const shouldEnsureController = options.controller !== false
+    && controllerSupportedPlatform(controllerPlatform)
+    && Boolean(options.apiKey)
+    && selfTestPassed
+    && !options.dryRun
+    && !options.doctor
+    && (options.yes || options.activate || options.repair);
+  if (shouldEnsureController) {
+    try {
+      controller = await ensureGovernanceController({
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+        agentId: options.agentId,
+        client,
+        root: detection.root,
+        mode: plan.mode,
+        profile: options.governanceMode || 'default',
+        policy: options.governancePolicy || 'warn',
+        platform: controllerPlatform,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      controller = {
+        active: false,
+        state: 'error',
+        exact_fix: 'Run npx @getmarrow/install controller ensure after correcting the reported local controller error.',
+        error: message,
+      };
+      if (options.activate) throw new Error(`Marrow activation failed: local controller did not start: ${message}`);
+    }
+  }
   const remediation = options.repair
     ? {
       attempted: true,
@@ -1614,16 +1679,17 @@ async function install(options) {
       missingEnv: options.apiKey ? [] : ['MARROW_API_KEY'],
       envHints,
       missingHooks: changes.filter((change) => change.changed).map((change) => change.label),
-      recommendedFix: configDiagnostics.npm_token.recommended_fix || selfTest.recommended_fix || (!options.apiKey
+      recommendedFix: configDiagnostics.npm_token.recommended_fix || (!options.apiKey
         ? envHints.length
           ? `MARROW_API_KEY was found in a likely env file at ${envHints[0]}. Load that key from trusted secret storage, export only MARROW_API_KEY, then run npx @getmarrow/install --repair.`
           : 'Set MARROW_API_KEY, then run npx @getmarrow/install --repair.'
-        : null),
+        : controller.exact_fix || selfTest.recommended_fix || null),
     },
     remediation,
     configDiagnostics,
     configRepairs,
     sdkDependency,
+    controller,
     selfTest,
     warnings: options.keyFromArg
       ? ['Avoid --key in shared shells because command-line arguments can be visible in process listings. Prefer MARROW_API_KEY in your environment or secret manager.']