@getmarrow/install 0.1.63 → 0.1.65

package/README.md

@@ -87,6 +87,8 @@ npx -y --package=@getmarrow/mcp@latest marrow-mcp ping
 
 `update` resolves official npm metadata once, selects one exact verified MCP target, and synchronizes every Marrow-managed surface in the detected owning workspace while retaining unrelated user hooks and configuration. Restart the detected owning harnesses once after it completes; running processes do not change before that restart. Run the doctor verification once after restart. Do not run separate `marrow-mcp setup` and restart cycles for the same detected workspace.
 
+`update` and `--repair` only refresh an existing install. Run from a directory with no Marrow-managed files while your home directory is managed, they stop without writing and print the exact `update --cwd <home>` command; to add Marrow to that project, run the install command there instead. Managed JSON that differs only in key order or formatting, for example after a harness re-saves its settings, counts as present and is not rewritten.
+
 `activate` remains available for initial activation. After explicit activation, the local controller can restore drifted Marrow-managed hooks and configuration. Package upgrades, owner policy, credentials, explicitly disabled hooks, and unrelated local files remain explicit and subject to the operator's normal change policy.
 
 ## Automatic Controller
@@ -101,7 +103,28 @@ npx @getmarrow/install controller stop
 
 Persistent controller lifecycle is currently Linux-only. On macOS or Windows, activation still writes supported configuration and verifies one server-side install self-test without certifying that hooks continuously ran; run `npx @getmarrow/install sidecar` under an owner-managed service and pass `--no-controller`. The controller does not silently upgrade packages, change governance policy, rotate credentials, or modify unrelated project configuration.
 
-## What's New in v0.1.63
+The controller is not a boot service. After a host restart, or any exit that skips its shutdown handler, doctor reports it as `stale` until the next install, update, or `controller ensure`. While local control is disabled, the controller is not started, and doctor reports a stopped or stale controller as not required instead of recommending `controller ensure`; unsafe controller state or an unverified or unresponsive controller process keeps its exact fix.
+
+## What's New in v0.1.65
+
+v0.1.65 pins MCP `3.9.97` (source `be607e1dffd4d9e6a3c40f01151e509c115fba3f`, packed integrity `sha512-wab1kvgec8WhDDrpkajauLu2QdADXudIxkic0BAgzV96FZVHY0ME45hrOyQmqfkI+OtKriYdgIFp90peWGh2mA==`) while keeping SDK `3.7.64` unchanged. Changes:
+
+- `doctor` no longer reports hooks as missing after a harness re-saves its settings file.
+- `update` refuses to write into an unrelated folder and only touches Marrow-managed roots.
+- The install self-test handles pending decisions and never commits one as a success.
+- Controller reporting is clearer; a disabled controller stays quiet while exact fixes for non-benign states are still shown.
+- Enforcement heartbeats back off after repeated failures and retry once an hour.
+- The agent id is never derived from the OS username.
+- Permit verification sends `protocol_version`.
+- The test suite is isolated from the real HOME and Marrow credentials.
+
+Restart the owning harness, review hook trust and run `doctor --self-test` after updating. Package publication and registry integrity verification must precede claiming these candidate pins are publicly available.
+
+### Previous release: v0.1.64
+
+v0.1.64 pins MCP `3.9.96` (source `031c944936271fd6e8768ad2619ee0430b68e2c7`, packed integrity `sha512-kuBpuWaWAvusS+FbXXFw1fOEGja4T8ahj/vkmXTd/CWjz0t6teT6g9c1HfJhAK6KLzesZtcvUdZLn6pBErKP9Q==`) while keeping SDK `3.7.64` unchanged. The embedded MCP pin requires this installer patch to deliver the native pre-action hook permit fix: protected actions are no longer denied after an allowing runtime gate, and unprotected actions stop at the gate without creating a decision or permit. Policy decisions, proof requirements and fail-closed behavior are unchanged. `activate` and `doctor --self-test` now resend the identical self-test decision and commit with a stable `Idempotency-Key` after a transient 429/502/503/504 or a durable pending acknowledgement (at most three attempts, about one second apart), instead of failing with "self-test did not return decision_id"; client errors still fail immediately, and a final failure names the last state. Restart the owning harness, review hook trust and run `doctor --self-test` after updating. Package publication and registry integrity verification must precede claiming these candidate pins are publicly available.
+
+### Previous release: v0.1.63
 
 v0.1.63 pins MCP `3.9.95` (source `967b17735b26534b7dc0536ec93c481a5dc07297`, packed integrity `sha512-Sw8RIyxHkjxllwwh+9za5ItoM9X0NwN4R8+Qdd7nvOuU6qAm9LotIC09GOJDim3o9jc9m8yTqxKciroRTS12EQ==`) while keeping SDK `3.7.64` unchanged. The embedded MCP pin requires this installer patch to deliver the stdin usage-loss correction and safe bounded native Codex capture. Supported transcript schema is Codex `0.157.1`; capture covers only the latest proven model-call delta. Unknown versions, missing model/turn or billing metadata, unsafe paths and unproven subagent bindings remain incomplete or unpriced. Capture does not prove a baseline, complete overhead or savings. Restart the owning harness and run `doctor --self-test` after updating. Package publication and registry integrity verification must precede claiming these candidate pins are publicly available.
 

package/package.json

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

package/src/controller-manager.js

@@ -12,7 +12,7 @@ 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';
+  const agentId = String(options.identityAgentId || 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);
 }
 
@@ -201,13 +201,17 @@ async function controllerStatus(options = {}) {
     const maintenance = body.maintenance && typeof body.maintenance === 'object'
       ? body.maintenance
       : null;
+    const heartbeat = body.heartbeat && typeof body.heartbeat === 'object'
+      ? body.heartbeat
+      : null;
     return {
       active: true,
       state: 'active',
       started_at: state.started_at,
       instance_id: state.instance_id,
       maintenance,
-      exact_fix: maintenance?.exact_fix || null,
+      heartbeat,
+      exact_fix: maintenance?.exact_fix || heartbeat?.exact_fix || null,
     };
   } catch {
     return {
@@ -233,8 +237,10 @@ function cleanControllerEnv(options) {
   }
   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;
+  if (options.agentId) {
+    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;
@@ -370,7 +376,7 @@ async function startGovernanceController(options) {
     const args = [
       binPath,
       'sidecar',
-      '--agent', options.agentId,
+      ...(options.agentId ? ['--agent', options.agentId] : []),
       '--client', options.client,
       '--profile', options.profile,
       '--policy', options.policy,

package/src/enforcement-client.js

@@ -1,5 +1,8 @@
 const crypto = require('node:crypto');
 
+// A background heartbeat must never hang on a stalled API response.
+const HEARTBEAT_REQUEST_TIMEOUT_MS = 15_000;
+
 function sha256(value) {
   return crypto.createHash('sha256').update(String(value || '')).digest('hex');
 }
@@ -17,11 +20,22 @@ function actionBinding(input) {
   };
 }
 
-async function enforcementRequest(requestJson, options, operation, input = {}) {
-  return requestJson(options, 'POST', '/v1/agent/enforcement', {
-    operation,
-    ...input,
-  });
+// The server resolves the key-bound or seat agent when no agent id is configured.
+function configuredAgentId(options) {
+  return String(options.agentId || '').trim() || undefined;
+}
+
+// Verify and close must declare the protocol the permit was issued under (1 or 2).
+function permitProtocolVersion(input) {
+  const version = input.protocolVersion ?? input.protocol_version;
+  return version === 1 || version === 2 ? version : 1;
+}
+
+async function enforcementRequest(requestJson, options, operation, input = {}, requestOptions = undefined) {
+  const body = { operation, ...input };
+  return requestOptions
+    ? requestJson(options, 'POST', '/v1/agent/enforcement', body, {}, requestOptions)
+    : requestJson(options, 'POST', '/v1/agent/enforcement', body);
 }
 
 async function issueActionPermit(requestJson, options, input) {
@@ -29,7 +43,7 @@ async function issueActionPermit(requestJson, options, input) {
   return enforcementRequest(requestJson, options, 'issue', {
     ...binding,
     session_id: options.sessionId,
-    agent_id: options.agentId,
+    agent_id: configuredAgentId(options),
     harness: options.client,
     policy_mode: options.policy,
     decision_id: input.decisionId || null,
@@ -46,8 +60,9 @@ async function verifyActionPermit(requestJson, options, input) {
     ...binding,
     surfaces: Array.isArray(input.surfaces) ? input.surfaces : [],
     permit: input.permit,
+    protocol_version: permitProtocolVersion(input),
     session_id: options.sessionId,
-    agent_id: options.agentId,
+    agent_id: configuredAgentId(options),
     harness: options.client,
   });
 }
@@ -58,22 +73,23 @@ async function closeActionPermit(requestJson, options, input) {
     permit_id: input.permitId || null,
     decision_id: input.decisionId || null,
     session_id: options.sessionId,
-    agent_id: options.agentId,
+    agent_id: configuredAgentId(options),
     success: Boolean(input.success),
     evidence: input.evidence || {},
+    protocol_version: permitProtocolVersion(input),
   });
 }
 
 async function recordEnforcementHeartbeat(requestJson, options, input = {}) {
   return enforcementRequest(requestJson, options, 'heartbeat', {
     session_id: options.sessionId,
-    agent_id: options.agentId,
+    agent_id: configuredAgentId(options),
     harness: options.client,
     sidecar_instance_id: input.sidecarInstanceId || null,
     config_fingerprint: input.configFingerprint || null,
     expected_hooks: input.expectedHooks || ['pre_action', 'action_result', 'outcome_closure'],
     observed_hooks: input.observedHooks || ['pre_action'],
-  });
+  }, { timeoutMs: HEARTBEAT_REQUEST_TIMEOUT_MS });
 }
 
 async function readEnforcementCoverage(requestJson, options) {
@@ -83,8 +99,10 @@ async function readEnforcementCoverage(requestJson, options) {
 }
 
 module.exports = {
+  HEARTBEAT_REQUEST_TIMEOUT_MS,
   actionBinding,
   sha256,
+  permitProtocolVersion,
   enforcementRequest,
   issueActionPermit,
   verifyActionPermit,

package/src/governance-sidecar.js

@@ -5,6 +5,87 @@ const os = require('node:os');
 const path = require('node:path');
 
 const MAX_BODY_BYTES = 64 * 1024;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_MAX_BACKOFF_MS = 30 * 60_000;
+const HEARTBEAT_CIRCUIT_THRESHOLD = 5;
+const HEARTBEAT_PROBE_MS = 60 * 60_000;
+const CONTROLLER_RESTART = 'npx @getmarrow/install controller stop && npx @getmarrow/install controller ensure';
+
+function heartbeatFailure(error) {
+  const status = Number.isInteger(error?.status) ? error.status : null;
+  const rawCode = error?.details?.code || error?.code;
+  const code = typeof rawCode === 'string' && /^[A-Za-z0-9_.:-]{1,80}$/.test(rawCode) ? rawCode : null;
+  return {
+    status,
+    code,
+    // A 4xx other than timeout or rate limit repeats until the request or its identity changes.
+    permanent: status !== null && status >= 400 && status < 500 && status !== 408 && status !== 429,
+    signature: `${status ?? 'network'}:${code ?? ''}`,
+  };
+}
+
+function heartbeatExactFix({ status, code }) {
+  const failure = `HTTP ${status}${code ? ` ${code}` : ''}`;
+  if (status === 404) {
+    return `Marrow has no registered agent for this controller (${failure}). Create the agent or bind this API key to a registered agent, set MARROW_FLEET_AGENT_ID to its id if the key is not bound, then run ${CONTROLLER_RESTART} to retry now.`;
+  }
+  if (status === 401 || status === 403) {
+    return `Marrow rejected this controller's API key or agent scope (${failure}). Use an active key bound to the registered agent, then run ${CONTROLLER_RESTART} to retry now.`;
+  }
+  return `Marrow rejected the controller heartbeat (${failure}). Run npx -y @getmarrow/install@latest update, then ${CONTROLLER_RESTART} to retry now.`;
+}
+
+// Heartbeats back off exponentially with jitter after any failure. Repeated identical 4xx
+// responses open the circuit: heartbeats then drop to one jittered probe about every hour,
+// so a fleet-wide transient 401/403/404 recovers without restarts. 5xx, 429, and network
+// failures keep retrying at the capped backoff. A notice is returned only when the circuit
+// opens, when its fix changes, and when heartbeats recover.
+function createHeartbeatPolicy({
+  intervalMs = HEARTBEAT_INTERVAL_MS,
+  maxBackoffMs = HEARTBEAT_MAX_BACKOFF_MS,
+  circuitThreshold = HEARTBEAT_CIRCUIT_THRESHOLD,
+  probeMs = HEARTBEAT_PROBE_MS,
+  random = Math.random,
+} = {}) {
+  let consecutive = 0;
+  let identical = 0;
+  let last = null;
+  let openFix = null;
+  return {
+    get open() { return openFix !== null; },
+    success() {
+      const recovered = openFix !== null;
+      consecutive = 0;
+      identical = 0;
+      last = null;
+      openFix = null;
+      return {
+        delayMs: intervalMs,
+        state: { state: 'ok', failures: 0, exact_fix: null },
+        notice: recovered ? 'Marrow controller resumed enforcement heartbeats.' : null,
+      };
+    },
+    failure(error) {
+      const failure = heartbeatFailure(error);
+      consecutive += 1;
+      identical = last?.signature === failure.signature ? identical + 1 : 1;
+      last = failure;
+      const summary = { status: failure.status, code: failure.code, failures: identical };
+      if (openFix !== null || (failure.permanent && identical >= circuitThreshold)) {
+        const fix = failure.permanent ? heartbeatExactFix(failure) : openFix;
+        const notice = fix === openFix
+          ? null
+          : `Marrow controller paused enforcement heartbeats and retries about once an hour. ${fix}`;
+        openFix = fix;
+        const delayMs = Math.round(probeMs * (0.75 + random() * 0.5));
+        return { delayMs, state: { state: 'circuit_open', ...summary, retry_in_ms: delayMs, exact_fix: fix }, notice };
+      }
+      const ceiling = Math.min(maxBackoffMs, intervalMs * 2 ** consecutive);
+      const delayMs = Math.round(ceiling / 2 + random() * (ceiling / 2));
+      return { delayMs, state: { state: 'backing_off', ...summary, retry_in_ms: delayMs, exact_fix: null }, notice: null };
+    },
+  };
+}
 
 function sidecarStateDir() {
   return process.env.MARROW_SIDECAR_STATE_DIR || path.join(os.homedir(), '.marrow', 'sidecar');
@@ -142,6 +223,7 @@ async function startGovernanceSidecar(options, handlers) {
     repaired: [],
     exact_fix: handlers.maintain ? null : 'Run npx @getmarrow/install --repair in the managed project.',
   };
+  let latestHeartbeat = { state: 'pending', failures: 0, exact_fix: null, checked_at: null };
 
   const server = http.createServer(async (req, res) => {
     try {
@@ -159,6 +241,7 @@ async function startGovernanceSidecar(options, handlers) {
           pid: process.pid,
           started_at: startedAt,
           maintenance: latestMaintenance,
+          heartbeat: latestHeartbeat,
         });
       }
       if (req.method === 'GET' && url.pathname === '/coverage') {
@@ -200,27 +283,54 @@ async function startGovernanceSidecar(options, handlers) {
     throw error;
   }
 
-  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.',
-        };
-      }
-    }
+  const heartbeatPolicy = createHeartbeatPolicy({
+    intervalMs: options.heartbeatIntervalMs,
+    probeMs: options.heartbeatProbeMs,
+    random: options.heartbeatRandom,
+  });
+  let nextHeartbeatAt = 0;
+  // Maintenance and heartbeat have separate in-flight guards, so a hung heartbeat request
+  // never stalls drift repair.
+  let maintenanceRunning = false;
+  let heartbeatRunning = false;
+  const runMaintenance = async () => {
+    if (!handlers.maintain || maintenanceRunning) return;
+    maintenanceRunning = true;
     try {
-      latestCoverage = await handlers.heartbeat({ sidecarInstanceId: instanceId });
+      latestMaintenance = await handlers.maintain();
     } catch {
-      // Coverage will mark stale heartbeat; never weaken execution policy here.
+      latestMaintenance = {
+        state: 'attention_required',
+        checked_at: new Date().toISOString(),
+        repaired: [],
+        exact_fix: 'Run npx @getmarrow/install --repair in the managed project.',
+      };
+    } finally {
+      maintenanceRunning = false;
+    }
+  };
+  const runHeartbeat = async () => {
+    if (heartbeatRunning || Date.now() < nextHeartbeatAt) return;
+    heartbeatRunning = true;
+    try {
+      let result;
+      try {
+        latestCoverage = await handlers.heartbeat({ sidecarInstanceId: instanceId });
+        result = heartbeatPolicy.success();
+      } catch (error) {
+        // Coverage will mark a stale heartbeat; never weaken execution policy here.
+        result = heartbeatPolicy.failure(error);
+      }
+      latestHeartbeat = { ...result.state, checked_at: new Date().toISOString() };
+      nextHeartbeatAt = Date.now() + result.delayMs;
+      if (result.notice) process.stderr.write(`${result.notice}\n`);
+    } finally {
+      heartbeatRunning = false;
     }
   };
-  await heartbeat();
-  const timer = setInterval(heartbeat, 30_000);
+  const tick = () => Promise.all([runMaintenance(), runHeartbeat()]);
+  await tick();
+  const timer = setInterval(tick, options.heartbeatIntervalMs || HEARTBEAT_INTERVAL_MS);
   timer.unref();
 
   let closed = false;
@@ -239,4 +349,4 @@ async function startGovernanceSidecar(options, handlers) {
   return { server, instanceId, port: boundPort, stateFile, close };
 }
 
-module.exports = { startGovernanceSidecar, sidecarStateDir };
+module.exports = { startGovernanceSidecar, sidecarStateDir, createHeartbeatPolicy };

package/src/governed-runner.js

@@ -352,7 +352,9 @@ function parseBaseOptions(argv, startIndex = 0) {
   const options = {
     apiKey: process.env.MARROW_API_KEY || process.env.MARROW_KEY || '',
     baseUrl: process.env.MARROW_BASE_URL || DEFAULT_BASE_URL,
-    agentId: process.env.MARROW_FLEET_AGENT_ID || process.env.MARROW_AGENT_ID || os.userInfo().username || 'agent',
+    // A local username is never a registered agent. With no configured id, the server
+    // resolves the key-bound agent or the plan seat instead.
+    agentId: process.env.MARROW_FLEET_AGENT_ID || process.env.MARROW_AGENT_ID || '',
     sessionId: process.env.MARROW_SESSION_ID || '',
     profile: process.env.MARROW_GOVERN_PROFILE || 'default',
     policy: process.env.MARROW_GOVERN_POLICY || 'enforce',
@@ -481,7 +483,6 @@ function headers(options) {
   const h = {
     Authorization: `Bearer ${options.apiKey}`,
     'Content-Type': 'application/json',
-    'X-Marrow-Agent-Id': options.agentId,
     'X-Marrow-Session-Id': options.sessionId,
     'X-Marrow-Client': sourceClient(options.client),
     'X-Marrow-Package': '@getmarrow/install',
@@ -491,6 +492,7 @@ function headers(options) {
     'X-Marrow-MCP-Version': ADAPTER_PROVENANCE.mcp.version,
     'User-Agent': '@getmarrow/install governed-runner',
   };
+  if (options.agentId) h['X-Marrow-Agent-Id'] = options.agentId;
   return h;
 }
 
@@ -501,7 +503,7 @@ function sourceMeta(options, channel, extra = {}) {
     client,
     harness: client,
     runner: '@getmarrow/install',
-    agent_id: options.agentId,
+    ...(options.agentId ? { agent_id: options.agentId } : {}),
     session_id: options.sessionId,
     profile: options.profile,
     governed: true,
@@ -514,12 +516,13 @@ function dataOf(json) {
   return json && typeof json === 'object' && json.data && typeof json.data === 'object' ? json.data : json;
 }
 
-async function requestJson(options, method, route, body, extraHeaders = {}) {
+async function requestJson(options, method, route, body, extraHeaders = {}, { timeoutMs } = {}) {
   if (!options.apiKey) throw new Error('MARROW_API_KEY is required. Use --fail-open only for non-production local commands.');
   const response = await fetch(new URL(route, options.baseUrl.replace(/\/$/, '/')), {
     method,
     headers: { ...headers(options), ...extraHeaders },
     body: body === undefined ? undefined : JSON.stringify(body),
+    ...(timeoutMs ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
   });
   const text = await response.text();
   let json = {};
@@ -613,7 +616,7 @@ async function recommendGovernanceMode(options, project = detectProjectSignals()
       environment: process.env.NODE_ENV || process.env.MARROW_GOVERN_PROFILE || options.profile,
     },
     agent: {
-      id: options.agentId,
+      id: options.agentId || undefined,
       role: 'setup',
     },
     source_meta: sourceMeta(options, 'mode_recommend', { action }),
@@ -631,7 +634,7 @@ async function recordGovernanceModeSelection(options, state) {
       environment: process.env.NODE_ENV || process.env.MARROW_GOVERN_PROFILE || options.profile,
     },
     agent: {
-      id: options.agentId,
+      id: options.agentId || undefined,
       role: 'setup',
     },
     selected_mode: selected,
@@ -842,6 +845,7 @@ async function runGoverned(parsed, execution = {}) {
         target,
         surfaces,
         permit: actionPermit.permit,
+        protocolVersion: actionPermit.protocol_version,
       });
       if (verified?.verified !== true) throw new Error('Marrow action permit verification failed.');
       permitVerified = true;
@@ -899,6 +903,7 @@ async function runGoverned(parsed, execution = {}) {
       permitClosed = await closeActionPermit(requestJson, options, {
         permit: actionPermit.permit,
         permitId: actionPermit.permit_id,
+        protocolVersion: actionPermit.protocol_version,
         decisionId,
         success,
         evidence: proof,
@@ -1017,7 +1022,9 @@ async function sidecarOnly(parsed) {
 }
 
 async function controllerOnly(parsed) {
-  const options = { ...parsed.options, root: process.cwd(), mode: 'auto' };
+  // Keep the local controller identity stable; only the server-facing agent id changed.
+  const identityAgentId = parsed.options.agentId || os.userInfo().username || 'agent';
+  const options = { ...parsed.options, identityAgentId, root: process.cwd(), mode: 'auto' };
   let result;
   if (parsed.action === 'ensure') result = await ensureGovernanceController(options);
   else if (parsed.action === 'start') result = await startGovernanceController(options);
@@ -1441,7 +1448,7 @@ function fleetPanel(snapshot) {
   return [
     'Marrow Fleet Operator',
     '',
-    `Agent: ${snapshot.agent_id}`,
+    `Agent: ${snapshot.agent_id || 'resolved by API key'}`,
     `Snapshot: ${snapshot.generated_at}`,
     '',
     `Live agents: ${snapshot.live_agents ?? 'unknown'}`,
@@ -1747,7 +1754,7 @@ async function integrationsOnly(parsed) {
 function governPanel(options) {
   const rows = detectHarnesses();
   const project = detectProjectSignals();
-  const agentId = displayText(options.agentId, 80);
+  const agentId = displayText(options.agentId, 80) || 'resolved by API key';
   const profile = displayText(options.profile, 80);
   const policy = displayText(options.policy, 24);
   const lines = [
@@ -1770,7 +1777,7 @@ function governPanel(options) {
       : '  recommendation: export MARROW_API_KEY to get an account/fleet-backed mode recommendation.',
     '',
     'Recommended first commands:',
-    `  npx @getmarrow/install run --agent ${shellQuoteDisplay(options.agentId)} --profile production --policy enforce -- codex`,
+    `  npx @getmarrow/install run ${options.agentId ? `--agent ${shellQuoteDisplay(options.agentId)} ` : ''}--profile production --policy enforce -- codex`,
     `  npx @getmarrow/install run --agent deploy-agent --type deploy --policy enforce -- wrangler deploy`,
     `  npx @getmarrow/install gate "deploy production worker after tests pass"`,
     '',
@@ -1817,7 +1824,7 @@ function commandForSelection(state, options) {
   }
   const command = harness.command === '<your-agent-command>' ? '<your-command>' : harness.command;
   const renderedCommand = command.split(/\s+/).filter(Boolean).map(shellQuote).join(' ');
-  return `MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run --agent ${shellQuoteDisplay(options.agentId)} --profile ${shellQuoteDisplay(options.profile)} --policy ${shellQuoteDisplay(mode.policy)} -- ${renderedCommand}`;
+  return `MARROW_API_KEY=mrw_live_xxx npx @getmarrow/install run ${options.agentId ? `--agent ${shellQuoteDisplay(options.agentId)} ` : ''}--profile ${shellQuoteDisplay(options.profile)} --policy ${shellQuoteDisplay(mode.policy)} -- ${renderedCommand}`;
 }
 
 function buildGovernState(options, cwd = process.cwd()) {
@@ -1910,7 +1917,7 @@ function renderGovernTui(state, options) {
     '| Passive agent governance for day-one use                   |',
     '+------------------------------------------------------------+',
     '',
-    `Agent: ${displayText(options.agentId, 36)}   Profile: ${displayText(options.profile, 24)}   API key: ${options.apiKey ? 'present' : 'missing'}`,
+    `Agent: ${displayText(options.agentId, 36) || 'resolved by API key'}   Profile: ${displayText(options.profile, 24)}   API key: ${options.apiKey ? 'present' : 'missing'}`,
     `Project: ${displayText(state.project?.name || 'workspace', 36)}   Signals: ${displayText((state.project?.signals || []).slice(0, 4).join(', ') || 'none', 52)}`,
     '',
     'Navigation: Up/Down move   Left/Right change   Enter select',
@@ -2036,7 +2043,7 @@ function renderFleetTui(state) {
     '| Live fleet health, proof debt, gates, and exact fixes       |',
     '+------------------------------------------------------------+',
     '',
-    `Agent: ${displayText(snapshot.agent_id, 36)}   Snapshot: ${displayText(snapshot.generated_at, 36)}`,
+    `Agent: ${displayText(snapshot.agent_id, 36) || 'resolved by API key'}   Snapshot: ${displayText(snapshot.generated_at, 36)}`,
     `API: ${displayText(snapshot.base_url, 60)}`,
     '',
     'Navigation: Up/Down move   Left/Right select agent   Enter inspect/print',
@@ -2419,6 +2426,7 @@ module.exports = {
   verifyPermitOnly,
   coverageOnly,
   sidecarOnly,
+  requestJson,
   controllerOnly,
   actionBinding,
   gateOnly,

package/src/installer.js

@@ -11,9 +11,9 @@ const { evidence: localControlEvidence } = require('./control-state');
 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.95';
-const MCP_ADAPTER_SOURCE_SHA = '967b17735b26534b7dc0536ec93c481a5dc07297';
-const MCP_ADAPTER_INTEGRITY = 'sha512-Sw8RIyxHkjxllwwh+9za5ItoM9X0NwN4R8+Qdd7nvOuU6qAm9LotIC09GOJDim3o9jc9m8yTqxKciroRTS12EQ==';
+const MCP_ADAPTER_VERSION = '3.9.97';
+const MCP_ADAPTER_SOURCE_SHA = 'be607e1dffd4d9e6a3c40f01151e509c115fba3f';
+const MCP_ADAPTER_INTEGRITY = 'sha512-wab1kvgec8WhDDrpkajauLu2QdADXudIxkic0BAgzV96FZVHY0ME45hrOyQmqfkI+OtKriYdgIFp90peWGh2mA==';
 const SDK_ADAPTER_VERSION = '3.7.64';
 const SDK_ADAPTER_INTEGRITY = 'sha512-8qJj/8ouHEz1NnZkmujtFxUm/fWldqR/rHv62/sqabaxT0H90xCCHxodLOkV0SVxDscAtnahioZakqkeGNUwyA==';
 const SDK_ADAPTER_TARBALL = `https://registry.npmjs.org/@getmarrow/sdk/-/sdk-${SDK_ADAPTER_VERSION}.tgz`;
@@ -968,6 +968,54 @@ function detectEnvironment(cwd = process.cwd(), env = process.env) {
   };
 }
 
+const MARROW_MANAGED_ROOT_FILES = Object.freeze([
+  'AGENTS.md',
+  'CLAUDE.md',
+  '.mcp.json',
+  path.join('.claude', 'settings.json'),
+  path.join('.codex', 'hooks.json'),
+  path.join('.cursor', 'hooks.json'),
+  path.join('.cursor', 'mcp.json'),
+  path.join('.cursor', 'rules', 'marrow.mdc'),
+  path.join('.windsurf', 'hooks.json'),
+  path.join('.gemini', 'settings.json'),
+  path.join('.clinerules', 'hooks', 'PreToolUse'),
+  path.join('.clinerules', 'hooks', 'PostToolUse'),
+  path.join('.clinerules', 'hooks', 'TaskCancel'),
+  path.join('.marrow', 'passive-runtime.mjs'),
+]);
+const MARROW_MANAGED_TEXT_RE = /@getmarrow\/mcp|marrow-mcp|<!-- marrow:passive-start -->/;
+
+function marrowManagedRootFiles(root) {
+  return MARROW_MANAGED_ROOT_FILES.filter((relative) => {
+    try {
+      const filePath = path.join(path.resolve(root), relative);
+      const stat = fs.lstatSync(filePath);
+      if (!stat.isFile() || stat.size > 2 * 1024 * 1024) return false;
+      return relative === path.join('.marrow', 'passive-runtime.mjs')
+        || MARROW_MANAGED_TEXT_RE.test(fs.readFileSync(filePath, 'utf8'));
+    } catch {
+      return false;
+    }
+  });
+}
+
+function shellArgument(value) {
+  return /^[A-Za-z0-9_./:@%+=-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function assertUpdateTargetsManagedRoot(detection) {
+  const root = path.resolve(detection.root);
+  const home = path.resolve(detection.home);
+  if (root === home || marrowManagedRootFiles(root).length > 0) return;
+  if (marrowManagedRootFiles(home).length === 0) return;
+  throw new Error([
+    `Refusing to update ${root}: it has no Marrow-managed files, and update never creates new Marrow project files in an unmanaged directory.`,
+    `Marrow-managed configuration was found at ${home}. To update it, run: ${INSTALLER_UPDATE_COMMAND} --cwd ${shellArgument(home)}`,
+    `To install Marrow into ${root} deliberately, run the install command from that directory instead: npx -y @getmarrow/install@latest`,
+  ].join('\n'));
+}
+
 function findLikelyEnvFiles(detection, env = process.env) {
   const home = env.HOME || env.USERPROFILE || os.homedir();
   const candidates = [
@@ -1248,6 +1296,28 @@ function parseJsonObject(filePath) {
   return parsed;
 }
 
+function canonicalJsonValue(value) {
+  if (Array.isArray(value)) return value.map(canonicalJsonValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalJsonValue(value[key])]));
+}
+
+function sameJsonDocument(left, right) {
+  try {
+    return JSON.stringify(canonicalJsonValue(JSON.parse(left.trim())))
+      === JSON.stringify(canonicalJsonValue(JSON.parse(right.trim())));
+  } catch {
+    return false;
+  }
+}
+
+// JSON.parse keeps the last duplicate key, so equal documents keep their bytes only when the
+// raw text also pins the same MCP versions; otherwise a stale earlier duplicate is never repaired.
+function equivalentManagedJson(before, after) {
+  const pinnedVersions = (text) => [...new Set(mcpVersionsInText(text))].sort().join(',');
+  return sameJsonDocument(before, after) && pinnedVersions(before) === pinnedVersions(after);
+}
+
 function upsertBlock(content, block) {
   if (content.includes(MARROW_BLOCK_START) && content.includes(MARROW_BLOCK_END)) {
     const start = content.indexOf(MARROW_BLOCK_START);
@@ -2598,12 +2668,14 @@ function applyPlan(plan, options) {
       after = upsertBlock(before, write.block);
     } else if (write.type === 'json-transform') {
       after = write.transform(write.path);
+      if (equivalentManagedJson(before, after)) after = before;
     } else if (write.type === 'managed-json-transform') {
       if (fileExists && !write.isManaged(write.path)) {
         after = before;
         hookConflict = true;
       } else {
         after = write.transform(write.path);
+        if (equivalentManagedJson(before, after)) after = before;
       }
     } else if (write.type === 'owned-executable') {
       if (fileExists && before !== write.content) {
@@ -2684,6 +2756,69 @@ async function requestJson(url, options) {
   return json.data || json;
 }
 
+const SELF_TEST_WRITE_ATTEMPTS = 3;
+const SELF_TEST_RETRY_DELAY_MS = 1_000;
+const SELF_TEST_MAX_RETRY_DELAY_MS = 2_000;
+const SELF_TEST_TRANSIENT_STATUSES = new Set([429, 502, 503, 504]);
+
+function selfTestRetryDelayMs(response, data, override) {
+  if (Number.isFinite(override) && override >= 0) return override;
+  const hinted = Number(data?.retry_after_ms);
+  const header = Number(response?.headers?.get?.('retry-after')) * 1000;
+  const delay = hinted > 0 ? hinted : header > 0 ? header : SELF_TEST_RETRY_DELAY_MS;
+  return Math.min(delay, SELF_TEST_MAX_RETRY_DELAY_MS);
+}
+
+// A first write can meet a transient 5xx, or a durable "pending" acknowledgement.
+// Marrow's contract is to resend the identical request with the same Idempotency-Key,
+// so a retry can never create a second record. As in the MCP client, a pending
+// acknowledgement is never complete, even when it names a created decision: that id
+// is pinned and the final response must carry the same one.
+async function selfTestWrite(url, options, { idempotencyKey, complete, retryDelayMs }) {
+  let lastState = 'no response';
+  let pinnedDecisionId = null;
+  for (let attempt = 1; attempt <= SELF_TEST_WRITE_ATTEMPTS; attempt += 1) {
+    const res = await fetch(url, { ...options, headers: { ...options.headers, 'idempotency-key': idempotencyKey } });
+    const text = await res.text();
+    let json = {};
+    try {
+      json = text ? JSON.parse(text) : {};
+    } catch {
+      json = { raw: text.slice(0, 500) };
+    }
+    const data = json.data || json;
+    if (res.ok) {
+      if (data?.idempotency_key !== undefined && data.idempotency_key !== idempotencyKey) {
+        throw new Error('self-test write returned a different idempotency key');
+      }
+      const decisionId = selfTestDecisionId(data);
+      if (pinnedDecisionId && decisionId && decisionId !== pinnedDecisionId) {
+        throw new Error('self-test write returned a different decision id than its pending acknowledgement');
+      }
+      if (data?.retryable !== true || data?.committed !== false) return complete(data);
+      if (data.idempotency_key !== idempotencyKey) {
+        throw new Error('self-test write returned a pending acknowledgement without its idempotency key');
+      }
+      if (decisionId && data.decision_state === 'created') pinnedDecisionId = decisionId;
+      lastState = 'pending';
+    } else if (SELF_TEST_TRANSIENT_STATUSES.has(res.status)) {
+      const reason = String(json.error || json.message || '').slice(0, 200);
+      lastState = reason ? `HTTP ${res.status}: ${reason}` : `HTTP ${res.status}`;
+    } else {
+      throw new Error(String(json.error || json.message || `HTTP ${res.status}`));
+    }
+    if (attempt < SELF_TEST_WRITE_ATTEMPTS) {
+      await new Promise((resolve) => setTimeout(resolve, selfTestRetryDelayMs(res, data, retryDelayMs)));
+    }
+  }
+  return { failed: lastState };
+}
+
+function selfTestDecisionId(data) {
+  const decisionId = data?.decision_id || data?.decisionId;
+  return typeof decisionId === 'string' && decisionId ? decisionId : undefined;
+}
+
 function runLoopGuardSelfTest(options = {}) {
   const target = executableMcpTarget(options);
   const isolatedHome = fs.mkdtempSync(path.join(os.tmpdir(), 'marrow-install-loop-guard-'));
@@ -2782,7 +2917,8 @@ async function runSelfTest(options) {
   if (options.agentId) headers['x-marrow-agent-id'] = options.agentId;
 
   const baseUrl = options.baseUrl.replace(/\/+$/, '');
-  const think = await requestJson(`${baseUrl}/v1/agent/think`, {
+  const selfTestKey = `install-self-test:${crypto.randomUUID()}`;
+  const think = await selfTestWrite(`${baseUrl}/v1/agent/think`, {
     method: 'POST',
     headers,
     body: JSON.stringify({
@@ -2794,12 +2930,18 @@ async function runSelfTest(options) {
         user_intent: 'operate',
       },
     }),
+  }, {
+    idempotencyKey: `${selfTestKey}:think`,
+    complete: (data) => selfTestDecisionId(data),
+    retryDelayMs: options.selfTestRetryDelayMs,
   });
 
-  const decisionId = think.decision_id || think.decisionId;
-  if (!decisionId) throw new Error('self-test did not return decision_id');
+  const decisionId = typeof think === 'string' ? think : undefined;
+  if (!decisionId) {
+    throw new Error(`self-test did not return decision_id${think?.failed ? ` after ${SELF_TEST_WRITE_ATTEMPTS} attempts (last: ${think.failed})` : ''}`);
+  }
 
-  await requestJson(`${baseUrl}/v1/agent/commit`, {
+  const commit = await selfTestWrite(`${baseUrl}/v1/agent/commit`, {
     method: 'POST',
     headers,
     body: JSON.stringify({
@@ -2807,7 +2949,14 @@ async function runSelfTest(options) {
       success: true,
       outcome: 'Marrow passive installer self-test completed successfully',
     }),
+  }, {
+    idempotencyKey: `${selfTestKey}:commit`,
+    complete: (data) => data,
+    retryDelayMs: options.selfTestRetryDelayMs,
   });
+  if (commit?.failed) {
+    throw new Error(`self-test commit did not complete after ${SELF_TEST_WRITE_ATTEMPTS} attempts (last: ${commit.failed})`);
+  }
 
   const status = await requestJson(`${baseUrl}/v1/agent/status`, { headers });
   const context = await requestJson(`${baseUrl}/v1/agent/context`, { headers })
@@ -3290,6 +3439,7 @@ function printReport(report) {
   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?.reason) process.stdout.write(`- reason: ${report.controller.reason}\n`);
   if (report.controller?.exact_fix) process.stdout.write(`- exact fix: ${report.controller.exact_fix}\n`);
 
   if (report.writeMode === 'doctor') {
@@ -3344,6 +3494,8 @@ function printReport(report) {
 }
 
 async function install(options) {
+  // The controller keeps the stable local id for its identity, but only sends a configured id.
+  const configuredAgentId = String(options.agentId || '').trim();
   if (options.activate && (options.yes !== true || options.dryRun || options.doctor)) {
     throw new Error('activate requires write mode (--yes) because hooks must be installed during this run');
   }
@@ -3364,6 +3516,7 @@ async function install(options) {
     HOME: options.home || options.cwd,
     USERPROFILE: options.home || options.cwd,
   });
+  if (options.repair || options.update) assertUpdateTargetsManagedRoot(detection);
   const client = detectedClient(detection);
   options.client = client;
   options.agentId = String(options.agentId || '').trim() || stableAgentId(detection.root, client);
@@ -3552,7 +3705,8 @@ async function install(options) {
       controller = await ensureGovernanceController({
         apiKey: options.apiKey,
         baseUrl: options.baseUrl,
-        agentId: options.agentId,
+        agentId: configuredAgentId,
+        identityAgentId: options.agentId,
         client,
         root: detection.root,
         mode: plan.mode,
@@ -3571,6 +3725,19 @@ async function install(options) {
       if (options.activate) throw new Error(`Marrow activation failed: local controller did not start: ${message}`);
     }
   }
+  // Only a controller that is simply not running is expected while the owner has disabled
+  // local control. Unsafe state, an unverified or unresponsive process, and unsupported
+  // platforms keep their exact fix.
+  if (localControl.state === 'disabled'
+    && controllerSupportedPlatform(controllerPlatform)
+    && ['stopped', 'stale'].includes(controller.state)) {
+    controller = {
+      ...controller,
+      required: false,
+      exact_fix: null,
+      reason: 'Local control is disabled by the owner, so the controller is intentionally not started. It starts again on the next install or update after npx @getmarrow/install control enable.',
+    };
+  }
   const remediation = options.repair
     ? {
       attempted: true,