@getmarrow/install 0.1.36 → 0.1.38

package/README.md

@@ -74,9 +74,44 @@ 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.38
+
+v0.1.38 makes a meaningful Marrow intervention visible without adding manual work to routine agent sessions:
+
+- generated instructions tell agents to retrieve and relay one factual intervention receipt after Marrow changes consequential work;
+- Fleet Reports surface the same receipt for owners, including the required workflow, proof status, permit follow-through, and recorded outcome;
+- agents remain quiet for routine low-risk work, and receipts exclude raw context, raw outcomes, proof values, credentials, and cross-tenant data.
+
+It preserves the automatic local control lifecycle introduced in v0.1.37.
+
+## Previous: 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 +235,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,13 +261,26 @@ 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.
 
 Meaningful work opens an outcome-closure item. A tool exit or workflow completion does not silently count as a successful business outcome; an explicit outcome receipt closes it. Transient delivery failures are held in an owner-only local spool and retried with the same event ID so retries do not create duplicate lifecycle records.
 
-Owners can inspect pending outcomes in Fleet Operations. Agents can retrieve a tenant-scoped causal trace for a decision to see the prior failure, lesson, gate, proof, workflow, and outcome path that changed the action.
+Owners can inspect pending outcomes in Fleet Operations and recent intervention receipts in Reports. Agents can retrieve the same tenant-scoped receipt through the decision trace to explain what Marrow blocked, warned about, or held for review; the required workflow; proof status; permit follow-through; and the recorded outcome. The receipt excludes raw context, raw outcomes, proof values, credentials, and other tenants' data. Agents should relay one factual receipt summary after a meaningful intervention and stay quiet for routine low-risk work.
 
 ## Passive Token and Value Proof
 

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.38",
   "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.54';
+const SDK_ADAPTER_VERSION = '3.7.53';
+const SDK_ADAPTER_INTEGRITY = 'sha512-CKPVR9gf24mNvZIcFvKhHGZSsUhxa0uDg/bN4dktLlttB/EU/p6CEVWmGqZmxDTnfp4I+qqdJUpzuQSnkNhaIA==';
 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
 `;
 }
@@ -435,6 +444,7 @@ Marrow should run passively after install:
 - Keep passive token/model usage proof enabled so Marrow can show token, cost, latency, and workflow savings after real work completes.
 - Before risky work, use Marrow's decision brief or passive prompt hook.
 - After meaningful work, record the outcome so future agents learn from it.
+- After Marrow blocks, warns, or requires review, use the decision trace receipt to tell the operator what changed and which recorded workflow or proof is required. Stay quiet for routine low-risk work.
 - Check health with \`marrow_agent_status\` or \`GET /v1/agent/status\`.
 - When status/runtime returns a \`client_update\` notice, tell the operator and use its exact update and verification commands only when local change policy permits.
 
@@ -1263,8 +1273,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 +1302,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 +1342,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 +1361,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 +1388,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 +1519,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 +1602,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 +1680,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.']