@muhaven/mcp 0.2.9 → 0.4.0

package/dist/broker.js

@@ -2,10 +2,12 @@ import path, { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { platform, release, hostname, homedir } from 'os';
 import { exec, spawn } from 'child_process';
+import { createInterface } from 'readline';
 import { connect, createServer } from 'net';
 import { mkdir, chmod, writeFile, readFile, unlink, rename, readdir, stat } from 'fs/promises';
 import { privateKeyToAccount, generatePrivateKey } from 'viem/accounts';
 import { randomBytes } from 'crypto';
+import { parseAbi, encodeFunctionData, decodeAbiParameters } from 'viem';
 
 var getFilename = () => fileURLToPath(import.meta.url);
 var getDirname = () => path.dirname(getFilename());
@@ -163,22 +165,45 @@ function loadBrokerConfig(env = process.env) {
     env.MUHAVEN_DASHBOARD_URL,
     DEFAULT_DASHBOARD_URL
   );
+  const chainRpcUrlRaw = readEnv("MUHAVEN_BROKER_RPC_URL", env) ?? readEnv("MUHAVEN_BUNDLER_URL", env);
+  const chainRpcUrl = chainRpcUrlRaw === void 0 ? void 0 : resolvePublicUrlEnv(
+    "MUHAVEN_BROKER_RPC_URL",
+    chainRpcUrlRaw,
+    chainRpcUrlRaw
+  );
+  const callbackServiceSecretRaw = readEnv("BROKER_CALLBACK_SERVICE_SECRET", env);
+  let callbackServiceSecret;
+  if (callbackServiceSecretRaw !== void 0) {
+    if (callbackServiceSecretRaw.length < 16) {
+      throw new Error(
+        "BROKER_CALLBACK_SERVICE_SECRET must be at least 16 characters (matches backend with-service-secret middleware floor)"
+      );
+    }
+    callbackServiceSecret = callbackServiceSecretRaw;
+  }
+  const outboundOriginHeader = readEnv("MUHAVEN_BROKER_ORIGIN", env) ?? dashboardBaseUrl;
   return {
     endpoint,
     sessionKeyHex,
     maxRequestBytes,
     requestTimeoutMs,
     backendBaseUrl,
-    dashboardBaseUrl
+    dashboardBaseUrl,
+    chainRpcUrl,
+    callbackServiceSecret,
+    outboundOriginHeader
   };
 }
 
 // src/broker/protocol.ts
-var BROKER_PROTOCOL_VERSION = "0.4.0";
+var BROKER_PROTOCOL_VERSION = "0.5.0";
 var HASH_HEX_RE = /^0x[0-9a-fA-F]{64}$/;
 var ADDRESS_HEX_RE2 = /^0x[0-9a-fA-F]{40}$/;
 var SELECTOR_HEX_RE = /^0x[0-9a-fA-F]{8}$/;
 var HEX_PREFIXED_RE = /^0x[0-9a-fA-F]*$/;
+var ENABLE_DATA_HEX_RE = /^0x[0-9a-fA-F]{2,65536}$/;
+var ENABLE_SIG_HEX_RE = /^0x[0-9a-fA-F]{256,16384}$/;
+var UINT32_MAX = 4294967295;
 var JWT_RE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
 var SESSION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 var UINT256_DEC_RE = /^(0|[1-9][0-9]{0,77})$/;
@@ -298,6 +323,43 @@ function parsePolicySnapshot(raw) {
   if (!isOptionalPermissionId(obj.permissionId)) {
     return { error: "snapshot.permissionId must be a 0x-prefixed 4-byte hex when provided" };
   }
+  const enableData = obj.enableData;
+  const enableSig = obj.enableSig;
+  const validatorNonce = obj.validatorNonce;
+  const installPresent = [enableData, enableSig, validatorNonce].filter(
+    (v) => v !== void 0
+  ).length;
+  if (installPresent !== 0 && installPresent !== 3) {
+    return {
+      error: "snapshot.{enableData,enableSig,validatorNonce} must be all-present or all-absent (Option D Commit 3 install-material trio)"
+    };
+  }
+  if (enableData !== void 0) {
+    if (typeof enableData !== "string" || !ENABLE_DATA_HEX_RE.test(enableData)) {
+      return {
+        error: "snapshot.enableData must be a 0x-prefixed hex string of 2..65536 chars when provided"
+      };
+    }
+  }
+  if (enableSig !== void 0) {
+    if (typeof enableSig !== "string" || !ENABLE_SIG_HEX_RE.test(enableSig)) {
+      return {
+        error: "snapshot.enableSig must be a 0x-prefixed hex string of 256..16384 chars (WebAuthn envelope) when provided"
+      };
+    }
+  }
+  if (validatorNonce !== void 0) {
+    if (typeof validatorNonce !== "number" || !Number.isInteger(validatorNonce) || validatorNonce < 0 || validatorNonce > UINT32_MAX) {
+      return {
+        error: "snapshot.validatorNonce must be an integer in [0, 2^32-1] when provided"
+      };
+    }
+  }
+  if (installPresent === 3 && obj.permissionId === void 0) {
+    return {
+      error: "snapshot install material requires permissionId in the same snapshot"
+    };
+  }
   return {
     sessionId: obj.sessionId,
     mode: "scoped",
@@ -310,7 +372,10 @@ function parsePolicySnapshot(raw) {
     mintedAtSec: obj.mintedAtSec,
     ...obj.consentActionHash === void 0 ? {} : { consentActionHash: obj.consentActionHash.toLowerCase() },
     ...obj.consentTextSha256 === void 0 ? {} : { consentTextSha256: obj.consentTextSha256.toLowerCase() },
-    ...obj.permissionId === void 0 ? {} : { permissionId: obj.permissionId.toLowerCase() }
+    ...obj.permissionId === void 0 ? {} : { permissionId: obj.permissionId.toLowerCase() },
+    ...enableData === void 0 ? {} : { enableData: enableData.toLowerCase() },
+    ...enableSig === void 0 ? {} : { enableSig: enableSig.toLowerCase() },
+    ...validatorNonce === void 0 ? {} : { validatorNonce }
   };
 }
 function parseBrokerRequest(line) {
@@ -489,6 +554,72 @@ function parseBrokerRequest(line) {
     }
     case "get_active_session_id":
       return { type: "get_active_session_id" };
+    case "current_nonce": {
+      if (!isAddressHex(obj.accountAddress)) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "current_nonce.accountAddress must be a 0x-prefixed 20-byte hex"
+        };
+      }
+      return {
+        type: "current_nonce",
+        accountAddress: obj.accountAddress.toLowerCase()
+      };
+    }
+    case "notify_userop_landed": {
+      if (!isSessionIdShape(obj.sessionId)) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.sessionId must be 1-128 chars [A-Za-z0-9_-]"
+        };
+      }
+      if (!isAddressHex(obj.accountAddress)) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.accountAddress must be a 0x-prefixed 20-byte hex"
+        };
+      }
+      if (!isSelectorHex(obj.permissionId)) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.permissionId must be a 0x-prefixed 4-byte hex"
+        };
+      }
+      if (!isHashHex(obj.txHash)) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.txHash must be a 0x-prefixed 32-byte hex"
+        };
+      }
+      if (typeof obj.blockNumber !== "number" || !Number.isFinite(obj.blockNumber) || !Number.isInteger(obj.blockNumber) || obj.blockNumber < 0) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.blockNumber must be a non-negative integer"
+        };
+      }
+      if (typeof obj.logIndex !== "number" || !Number.isFinite(obj.logIndex) || !Number.isInteger(obj.logIndex) || obj.logIndex < 0) {
+        return {
+          type: "error",
+          code: "invalid_request",
+          message: "notify_userop_landed.logIndex must be a non-negative integer"
+        };
+      }
+      return {
+        type: "notify_userop_landed",
+        sessionId: obj.sessionId,
+        accountAddress: obj.accountAddress.toLowerCase(),
+        permissionId: obj.permissionId.toLowerCase(),
+        txHash: obj.txHash.toLowerCase(),
+        blockNumber: obj.blockNumber,
+        logIndex: obj.logIndex
+      };
+    }
     default:
       return {
         type: "error",
@@ -648,6 +779,33 @@ var BrokerClient = class {
     }
     return res;
   }
+  // ── Wave 5 Option D Commit 3 — install-mode pre-check + callback notify ──
+  async currentNonce(accountAddress) {
+    const res = await this.exchange({ type: "current_nonce", accountAddress });
+    if (res.type !== "current_nonce") {
+      throw new BrokerClientError(
+        "protocol_error",
+        `expected current_nonce response, got ${res.type}`
+      );
+    }
+    if (res.accountAddress.toLowerCase() !== accountAddress.toLowerCase()) {
+      throw new BrokerClientError(
+        "protocol_error",
+        `current_nonce echo mismatch (requested ${accountAddress}, got ${res.accountAddress})`
+      );
+    }
+    return res;
+  }
+  async notifyUseropLanded(args) {
+    const res = await this.exchange({ type: "notify_userop_landed", ...args });
+    if (res.type !== "notify_userop_landed") {
+      throw new BrokerClientError(
+        "protocol_error",
+        `expected notify_userop_landed response, got ${res.type}`
+      );
+    }
+    return res;
+  }
   /**
    * Detect whether the running daemon speaks Path D (protocol 0.4.0+).
    * Wraps `hello()` with a semver-gte comparison so the MCP tool layer
@@ -1438,11 +1596,285 @@ function checkPolicy(input) {
   }
   return { ok: true };
 }
+var KERNEL_V3_CURRENT_NONCE_ABI = parseAbi([
+  "function currentNonce() view returns (uint32)"
+]);
+var ChainRpcError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "ChainRpcError";
+  }
+  cause;
+};
+var CallbackError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "CallbackError";
+  }
+  cause;
+};
+var CALLBACK_RETRY_SCHEDULE_MS = [
+  5e3,
+  15e3,
+  6e4,
+  5 * 6e4
+];
+var CALLBACK_MAX_ELAPSED_MS = 60 * 6e4;
+var DEFAULT_FETCH_TIMEOUT_MS = 15e3;
+var BrokerOutbound = class {
+  constructor(config, log = () => {
+  }) {
+    this.config = config;
+    this.log = log;
+    this.fetchImpl = config.fetchImpl ?? fetch;
+    this.fetchTimeoutMs = config.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    this.setTimeoutImpl = config.setTimeout ?? setTimeout;
+    this.clearTimeoutImpl = config.clearTimeout ?? clearTimeout;
+  }
+  config;
+  log;
+  fetchImpl;
+  fetchTimeoutMs;
+  setTimeoutImpl;
+  clearTimeoutImpl;
+  /**
+   * Wave 5 Option D Commit 3 (multi-agent review SecEng-MED-3) —
+   * in-process dedup of `notify_userop_landed` callbacks. Map of
+   * `<sessionId>:<txHash>` → the in-flight retry loop's Promise.
+   * Repeated IPC calls with the same key fold into the existing
+   * loop instead of spawning a parallel POST. Defends against a
+   * local-socket peer flooding the broker with replay attempts +
+   * caps the retry-budget waste at one loop per real install.
+   */
+  inflightCallbacks = /* @__PURE__ */ new Map();
+  /**
+   * Read the kernel's `currentNonce()` view via `eth_call` against the
+   * configured chain RPC. Returns a uint32. Throws `ChainRpcError` when
+   * unconfigured / network failed / RPC returned non-decodable bytes.
+   */
+  async currentNonce(accountAddress) {
+    if (!this.config.chainRpcUrl) {
+      throw new ChainRpcError(
+        "broker chain RPC unconfigured \u2014 set MUHAVEN_BROKER_RPC_URL or MUHAVEN_BUNDLER_URL"
+      );
+    }
+    const data = encodeFunctionData({
+      abi: KERNEL_V3_CURRENT_NONCE_ABI,
+      functionName: "currentNonce"
+    });
+    const body = JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "eth_call",
+      params: [{ to: accountAddress, data }, "latest"]
+    });
+    let res;
+    const ac = new AbortController();
+    const timer = this.setTimeoutImpl(() => ac.abort(), this.fetchTimeoutMs);
+    try {
+      res = await this.fetchImpl(this.config.chainRpcUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          Origin: this.config.outboundOriginHeader
+        },
+        body,
+        signal: ac.signal
+      });
+    } catch (err) {
+      throw new ChainRpcError(
+        `chain RPC fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+        err
+      );
+    } finally {
+      this.clearTimeoutImpl(timer);
+    }
+    if (!res.ok) {
+      throw new ChainRpcError(
+        `chain RPC returned HTTP ${res.status}`
+      );
+    }
+    let parsed;
+    try {
+      parsed = await res.json();
+    } catch (err) {
+      throw new ChainRpcError(
+        `chain RPC returned non-JSON: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (parsed.error) {
+      throw new ChainRpcError(
+        `chain RPC error: ${parsed.error.message ?? "unknown"}`
+      );
+    }
+    if (typeof parsed.result !== "string" || !/^0x[0-9a-fA-F]*$/.test(parsed.result)) {
+      throw new ChainRpcError(
+        `chain RPC returned non-hex result: ${JSON.stringify(parsed.result).slice(0, 80)}`
+      );
+    }
+    let nonce;
+    try {
+      const decoded = decodeAbiParameters(
+        [{ type: "uint32" }],
+        parsed.result
+      );
+      nonce = Number(decoded[0]);
+    } catch (err) {
+      throw new ChainRpcError(
+        `failed to decode currentNonce result: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (!Number.isFinite(nonce) || nonce < 0 || nonce > 4294967295) {
+      throw new ChainRpcError(`currentNonce out of uint32 range: ${nonce}`);
+    }
+    return nonce;
+  }
+  /**
+   * Whether the callback path is wired (both secret + backend URL set).
+   * The `notify_userop_landed` daemon handler checks this and returns
+   * `callback_unconfigured` when false so the operator sees the gap.
+   */
+  isCallbackConfigured() {
+    return Boolean(this.config.callbackServiceSecret) && Boolean(this.config.backendBaseUrl);
+  }
+  /**
+   * Queue a `validator-enabled` callback POST to the backend. Returns
+   * immediately; the retry loop runs in the background (5s / 15s / 60s
+   * / 5m, max 1h elapsed). Failures are logged but do NOT propagate to
+   * the IPC caller — the chain indexer is the authoritative safety
+   * net.
+   *
+   * Idempotency: every POST carries an `Idempotency-Key` header
+   * `<sessionId>:validator-enabled`. The backend route is no-op if the
+   * mirror row's `enable_status` is already `'enabled'` (because the
+   * chain indexer raced ahead).
+   *
+   * Returns a Promise resolved when the loop terminates (success or
+   * max-elapsed). Callers don't need to await; tests use it for
+   * deterministic assertions.
+   */
+  enqueueValidatorEnabledCallback(args) {
+    if (!this.isCallbackConfigured()) {
+      return Promise.resolve({
+        ok: false,
+        attempts: 0,
+        lastError: "callback_unconfigured"
+      });
+    }
+    const dedupKey = `${args.sessionId}:${args.txHash.toLowerCase()}:${args.accountAddress.toLowerCase()}`;
+    const existing = this.inflightCallbacks.get(dedupKey);
+    if (existing) {
+      this.log("info", "validator-enabled callback already in flight \u2014 folded", {
+        sessionId: args.sessionId
+      });
+      return existing;
+    }
+    const promise = this.runCallbackLoop(args).finally(() => {
+      this.inflightCallbacks.delete(dedupKey);
+    });
+    this.inflightCallbacks.set(dedupKey, promise);
+    return promise;
+  }
+  async runCallbackLoop(args) {
+    const url = `${this.config.backendBaseUrl.replace(/\/+$/, "")}/api/v1/agent/policy/scoped-session/${encodeURIComponent(args.sessionId)}/validator-enabled`;
+    const body = JSON.stringify({
+      userId: args.userId,
+      accountAddress: args.accountAddress,
+      permissionId: args.permissionId,
+      txHash: args.txHash,
+      blockNumber: args.blockNumber,
+      logIndex: args.logIndex
+    });
+    const startedAt = Date.now();
+    let attempts = 0;
+    let lastError;
+    for (let i = 0; i <= CALLBACK_RETRY_SCHEDULE_MS.length; i++) {
+      if (i > 0) {
+        const delay = CALLBACK_RETRY_SCHEDULE_MS[i - 1] ?? 0;
+        const elapsed = Date.now() - startedAt;
+        if (elapsed + delay > CALLBACK_MAX_ELAPSED_MS) {
+          lastError = `retry budget exhausted after ${attempts} attempts (last error: ${lastError ?? "unknown"})`;
+          this.log("error", "validator-enabled callback abandoned", {
+            sessionId: args.sessionId,
+            attempts,
+            lastError
+          });
+          return { ok: false, attempts, lastError };
+        }
+        await this.sleep(delay);
+      }
+      attempts++;
+      try {
+        const ok = await this.postCallback(url, body, args.sessionId);
+        if (ok) {
+          this.log("info", "validator-enabled callback succeeded", {
+            sessionId: args.sessionId,
+            attempts
+          });
+          return { ok: true, attempts };
+        }
+        lastError = "non-2xx response";
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+        this.log("warn", "validator-enabled callback attempt failed", {
+          sessionId: args.sessionId,
+          attempt: attempts,
+          err: lastError
+        });
+      }
+    }
+    this.log("error", "validator-enabled callback retry budget exhausted", {
+      sessionId: args.sessionId,
+      attempts,
+      lastError
+    });
+    return { ok: false, attempts, lastError };
+  }
+  async postCallback(url, body, sessionId) {
+    const ac = new AbortController();
+    const timer = this.setTimeoutImpl(() => ac.abort(), this.fetchTimeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          Authorization: `Bearer ${this.config.callbackServiceSecret}`,
+          "Idempotency-Key": `${sessionId}:validator-enabled`,
+          Origin: this.config.outboundOriginHeader
+        },
+        body,
+        signal: ac.signal
+      });
+    } finally {
+      this.clearTimeoutImpl(timer);
+    }
+    if (res.status === 409) {
+      this.log("info", "callback returned 409 (row already enabled \u2014 idempotent)", {
+        sessionId
+      });
+      return true;
+    }
+    if (res.ok) return true;
+    throw new CallbackError(
+      `backend callback returned HTTP ${res.status}`
+    );
+  }
+  sleep(ms) {
+    return new Promise((resolve) => {
+      this.setTimeoutImpl(() => resolve(), ms);
+    });
+  }
+};
 
 // src/broker/daemon.ts
 var noopLogger = (_e) => {
 };
-async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.floor(Date.now() / 1e3), options = {}, policyStore) {
+async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.floor(Date.now() / 1e3), options = {}, policyStore, outbound) {
   switch (req.type) {
     case "hello": {
       let hasJwt = false;
@@ -1650,6 +2082,57 @@ async function handleBrokerRequest(req, signer, keystore, nowSec = () => Math.fl
         );
       }
     }
+    case "current_nonce": {
+      if (!outbound) {
+        return errorResponse(
+          "chain_rpc_failed",
+          "broker daemon was not configured with a chain RPC URL"
+        );
+      }
+      try {
+        const nonce = await outbound.currentNonce(req.accountAddress);
+        return {
+          type: "current_nonce",
+          nonce,
+          accountAddress: req.accountAddress
+        };
+      } catch (err) {
+        if (err instanceof ChainRpcError) {
+          return errorResponse("chain_rpc_failed", err.message);
+        }
+        return errorResponse(
+          "chain_rpc_failed",
+          err instanceof Error ? err.message : "chain RPC eth_call failed"
+        );
+      }
+    }
+    case "notify_userop_landed": {
+      if (!outbound) {
+        return errorResponse(
+          "callback_unconfigured",
+          "broker daemon was not configured with the callback service secret"
+        );
+      }
+      if (!outbound.isCallbackConfigured()) {
+        return errorResponse(
+          "callback_unconfigured",
+          "BROKER_CALLBACK_SERVICE_SECRET or backend URL is unset \u2014 validator-enabled callback skipped (chain indexer is the safety net)"
+        );
+      }
+      void outbound.enqueueValidatorEnabledCallback({
+        sessionId: req.sessionId,
+        accountAddress: req.accountAddress,
+        permissionId: req.permissionId,
+        txHash: req.txHash,
+        blockNumber: req.blockNumber,
+        logIndex: req.logIndex
+      });
+      return {
+        type: "notify_userop_landed",
+        queued: true,
+        sessionId: req.sessionId
+      };
+    }
   }
 }
 function errorResponse(code, message) {
@@ -1680,6 +2163,7 @@ var BrokerDaemon = class {
   config;
   keystore;
   policyStore;
+  outbound;
   /**
    * Whether a session-key private half is actually loaded. `false` =
    * daemon booted in read-only posture (no `MUHAVEN_BROKER_SESSION_KEY`
@@ -1700,6 +2184,15 @@ var BrokerDaemon = class {
     }
     this.keystore = options.keystore ?? null;
     this.policyStore = options.policyStore ?? new FilePolicyStore(FilePolicyStore.defaultDir());
+    this.outbound = options.outbound ?? new BrokerOutbound(
+      {
+        chainRpcUrl: options.config.chainRpcUrl,
+        backendBaseUrl: options.config.backendBaseUrl,
+        callbackServiceSecret: options.config.callbackServiceSecret,
+        outboundOriginHeader: options.config.outboundOriginHeader ?? options.config.dashboardBaseUrl
+      },
+      (level, msg, meta) => (options.logger ?? noopLogger)({ level, msg, meta })
+    );
     this.log = options.logger ?? noopLogger;
     this.server = createServer((socket) => this.onConnection(socket));
   }
@@ -1832,7 +2325,8 @@ var BrokerDaemon = class {
           },
           pid: process.pid
         },
-        this.policyStore
+        this.policyStore,
+        this.outbound
       );
       socket.end(serializeResponse(res));
     } catch (err) {
@@ -1875,6 +2369,63 @@ async function runBrokerDaemonCli() {
   await new Promise(() => {
   });
 }
+
+// src/broker/session-input.ts
+var SESSION_KEY_HEX_RE = /^0x[0-9a-fA-F]{64}$/;
+function validateSessionKeyShape(key) {
+  if (key.length === 0) return "session key is empty";
+  if (!key.startsWith("0x")) return "session key must be 0x-prefixed";
+  if (!SESSION_KEY_HEX_RE.test(key)) {
+    return `session key must be a 0x-prefixed 32-byte hex string (got ${key.length} chars; expected 66)`;
+  }
+  return null;
+}
+async function resolveSessionKey(opts) {
+  const { sessionFlag, policy, deps } = opts;
+  if (sessionFlag !== void 0) {
+    let raw;
+    if (sessionFlag === "-") {
+      const stdin = await deps.readStdinAll();
+      raw = stdin.trim();
+      if (raw.length === 0) {
+        return { kind: "error", message: "--session - was given but stdin was empty" };
+      }
+    } else {
+      raw = sessionFlag.trim();
+    }
+    const shapeErr2 = validateSessionKeyShape(raw);
+    if (shapeErr2) return { kind: "error", message: shapeErr2 };
+    return { kind: "key", key: raw };
+  }
+  if (!deps.isTty) {
+    if (policy === "mint-fallback") return { kind: "mint" };
+    return {
+      kind: "error",
+      message: "no session key provided and stdin is not a TTY \u2014 pass --session <key> (or `--session -` to pipe it), or run `muhaven-broker setup` to mint a fresh key"
+    };
+  }
+  const hasKey = await deps.promptYesNo(
+    "Do you have a session key from the dashboard? [Y/n] "
+  );
+  if (!hasKey) {
+    if (policy === "mint-fallback") return { kind: "mint" };
+    return {
+      kind: "error",
+      message: "a session key is required for this command \u2014 paste the dashboard-minted key, or run `muhaven-broker setup` to mint one"
+    };
+  }
+  const pasted = (await deps.promptSecret("Paste the session key: ")).trim();
+  const shapeErr = validateSessionKeyShape(pasted);
+  if (shapeErr) {
+    return {
+      kind: "error",
+      message: `${shapeErr} \u2014 re-run and paste the key from the dashboard's session-reveal modal`
+    };
+  }
+  return { kind: "key", key: pasted };
+}
+
+// src/broker/setup.ts
 var DANGEROUS_NODE_ENV_VARS = [
   "NODE_OPTIONS",
   "NODE_TLS_REJECT_UNAUTHORIZED",
@@ -1962,6 +2513,26 @@ function validateBrokerEndpointFlag(value, platformId) {
   }
   return null;
 }
+var LOGIN_SEED_ENV_KEYS = [
+  "MUHAVEN_BACKEND_URL",
+  "MUHAVEN_DASHBOARD_URL",
+  "MUHAVEN_BROKER_ENDPOINT"
+];
+async function withSeededLoginEnv(effectiveEnv, fn) {
+  const originalValues = {};
+  for (const k of LOGIN_SEED_ENV_KEYS) {
+    originalValues[k] = process.env[k];
+    if (effectiveEnv[k]) process.env[k] = effectiveEnv[k];
+  }
+  try {
+    return await fn();
+  } finally {
+    for (const k of LOGIN_SEED_ENV_KEYS) {
+      if (originalValues[k] === void 0) delete process.env[k];
+      else process.env[k] = originalValues[k];
+    }
+  }
+}
 var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function waitForBroker(options) {
   const timeoutMs = options.timeoutMs ?? 8e3;
@@ -2211,12 +2782,32 @@ async function runSetup(argv, deps) {
   }
   let sessionKey = effectiveEnv.MUHAVEN_BROKER_SESSION_KEY;
   let mintedKey = false;
-  if (!sessionKey || sessionKey === "") {
-    sessionKey = deps.mintSessionKey();
-    mintedKey = true;
-    deps.print("Session key: minted fresh (secp256k1, ephemeral to this daemon).");
-  } else {
+  if (sessionKey && sessionKey.length > 0) {
     deps.print("Session key: using MUHAVEN_BROKER_SESSION_KEY from env.");
+  } else {
+    const sessionInput = deps.sessionInput ?? {
+      isTty: false,
+      readStdinAll: async () => "",
+      promptYesNo: async () => false,
+      promptSecret: async () => ""
+    };
+    const resolution = await resolveSessionKey({
+      sessionFlag: void 0,
+      policy: "mint-fallback",
+      deps: sessionInput
+    });
+    if (resolution.kind === "error") {
+      deps.printErr(`error: ${resolution.message}`);
+      return 2;
+    }
+    if (resolution.kind === "key") {
+      sessionKey = resolution.key;
+      deps.print("Session key: using the pasted dashboard key.");
+    } else {
+      sessionKey = deps.mintSessionKey();
+      mintedKey = true;
+      deps.print("Session key: minted fresh (secp256k1, ephemeral to this daemon).");
+    }
   }
   effectiveEnv.MUHAVEN_BROKER_SESSION_KEY = sessionKey;
   if (flags.foreground) {
@@ -2300,21 +2891,7 @@ async function runSetup(argv, deps) {
     if (flags.dashboardBaseUrl) {
       loginArgv.push("--dashboard-base-url", flags.dashboardBaseUrl);
     }
-    const restorationKeys = ["MUHAVEN_BACKEND_URL", "MUHAVEN_DASHBOARD_URL", "MUHAVEN_BROKER_ENDPOINT"];
-    const originalValues = {};
-    for (const k of restorationKeys) {
-      originalValues[k] = process.env[k];
-      if (effectiveEnv[k]) process.env[k] = effectiveEnv[k];
-    }
-    let code;
-    try {
-      code = await deps.runLogin(loginArgv);
-    } finally {
-      for (const k of restorationKeys) {
-        if (originalValues[k] === void 0) delete process.env[k];
-        else process.env[k] = originalValues[k];
-      }
-    }
+    const code = await withSeededLoginEnv(effectiveEnv, () => deps.runLogin(loginArgv));
     if (code !== 0) {
       deps.printErr(
         "Setup: login step failed \u2014 daemon is still running, re-run `muhaven-broker login` to retry."
@@ -2398,13 +2975,15 @@ async function runStop(deps) {
     deps.print("Broker daemon: not running, nothing to stop.");
     return 0;
   }
-  try {
-    await broker.clearJwt();
-    deps.print("JWT cleared from keystore.");
-  } catch (err) {
-    deps.print(
-      `Warning: clearJwt failed (${err instanceof Error ? err.message : String(err)}); continuing with daemon shutdown.`
-    );
+  if (deps.clearJwtOnStop ?? true) {
+    try {
+      await broker.clearJwt();
+      deps.print("JWT cleared from keystore.");
+    } catch (err) {
+      deps.print(
+        `Warning: clearJwt failed (${err instanceof Error ? err.message : String(err)}); continuing with daemon shutdown.`
+      );
+    }
   }
   const pid = hello.pid;
   if (pid === void 0) {
@@ -2462,6 +3041,190 @@ function defaultKillProcess(pid, signal) {
   }
 }
 
+// src/broker/bring-up.ts
+function parseBringUpFlags(argv) {
+  let session;
+  let noLaunchBrowser = false;
+  let skipLogin = false;
+  let brokerEndpoint;
+  let backendBaseUrl;
+  let dashboardBaseUrl;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--no-launch-browser") noLaunchBrowser = true;
+    else if (a === "--skip-login") skipLogin = true;
+    else if (a === "--session") {
+      const next = argv[i + 1];
+      if (next === void 0) {
+        throw new Error("--session requires a value (a 0x\u2026 key, or `-` to read from stdin)");
+      }
+      if (next !== "-" && next.startsWith("-")) {
+        throw new Error(`--session requires a key value (or \`-\` for stdin), got flag: ${next}`);
+      }
+      session = argv[++i];
+    } else if (a === "--broker-endpoint" && i + 1 < argv.length) brokerEndpoint = argv[++i];
+    else if (a === "--backend-base-url" && i + 1 < argv.length) backendBaseUrl = argv[++i];
+    else if (a === "--dashboard-base-url" && i + 1 < argv.length) dashboardBaseUrl = argv[++i];
+    else throw new Error(`unknown flag: ${a}`);
+  }
+  return { session, noLaunchBrowser, skipLogin, brokerEndpoint, backendBaseUrl, dashboardBaseUrl };
+}
+function usageLine(mode) {
+  return `usage: muhaven-broker ${mode} --session <key|-> [--no-launch-browser] [--skip-login]
+                            [--broker-endpoint PATH] [--backend-base-url URL]
+                            [--dashboard-base-url URL]
+       (omit --session to be asked interactively; pipe the key with \`--session -\`)`;
+}
+async function runBringUp(mode, argv, deps) {
+  let flags;
+  try {
+    flags = parseBringUpFlags(argv);
+  } catch (err) {
+    deps.printErr(`error: ${err.message}`);
+    deps.printErr(usageLine(mode));
+    return 2;
+  }
+  if (flags.backendBaseUrl) {
+    const e = validateHttpUrlFlag("--backend-base-url", flags.backendBaseUrl);
+    if (e) {
+      deps.printErr(`error: ${e}`);
+      return 2;
+    }
+  }
+  if (flags.dashboardBaseUrl) {
+    const e = validateHttpUrlFlag("--dashboard-base-url", flags.dashboardBaseUrl);
+    if (e) {
+      deps.printErr(`error: ${e}`);
+      return 2;
+    }
+  }
+  if (flags.brokerEndpoint) {
+    const e = validateBrokerEndpointFlag(flags.brokerEndpoint, deps.platformId);
+    if (e) {
+      deps.printErr(`error: ${e}`);
+      return 2;
+    }
+  }
+  const resolution = await resolveSessionKey({
+    sessionFlag: flags.session,
+    policy: "require",
+    deps: deps.sessionPrompt
+  });
+  if (resolution.kind !== "key") {
+    const message = resolution.kind === "error" ? resolution.message : "no session key resolved";
+    deps.printErr(`error: ${message}`);
+    return 2;
+  }
+  const sessionKey = resolution.key;
+  const overrides = applyEnvDefaults({
+    env: deps.env,
+    platformId: deps.platformId,
+    osRelease: deps.osRelease
+  });
+  const effectiveEnv = {};
+  for (const [k, v] of Object.entries(deps.env)) {
+    if (typeof v === "string") effectiveEnv[k] = v;
+  }
+  for (const [k, v] of Object.entries(overrides.toSet)) effectiveEnv[k] = v;
+  if (flags.brokerEndpoint) effectiveEnv.MUHAVEN_BROKER_ENDPOINT = flags.brokerEndpoint;
+  if (flags.backendBaseUrl) effectiveEnv.MUHAVEN_BACKEND_URL = flags.backendBaseUrl;
+  if (flags.dashboardBaseUrl) effectiveEnv.MUHAVEN_DASHBOARD_URL = flags.dashboardBaseUrl;
+  for (const name of overrides.preserved) deps.print(`Env preserved: ${name} (set in your shell)`);
+  for (const [k, v] of Object.entries(overrides.toSet)) deps.print(`Env defaulted: ${k}=${v}`);
+  const config = loadMcpConfig(effectiveEnv);
+  const broker = deps.newBrokerClient(config.brokerEndpoint, config.brokerTimeoutMs);
+  let running = false;
+  try {
+    await broker.hello();
+    running = true;
+  } catch {
+    running = false;
+  }
+  if (mode === "start") {
+    if (running) {
+      deps.printErr(
+        `Broker daemon is already running at ${config.brokerEndpoint}. To rotate its key use:  muhaven-broker update --session <key>`
+      );
+      return 1;
+    }
+    deps.print("Broker daemon: not running \u2014 starting one (detached) on the provided key ...");
+  } else {
+    if (running) {
+      deps.print("Broker daemon: running \u2014 stopping it before installing the new key ...");
+      const stopCode = await deps.stopDaemon(config.brokerEndpoint, config.brokerTimeoutMs);
+      if (stopCode !== 0) {
+        deps.printErr(
+          `Broker daemon stop returned ${stopCode}; refusing to start a second daemon on the same endpoint. Resolve the running daemon (muhaven-broker doctor) and retry.`
+        );
+        return stopCode;
+      }
+    } else {
+      deps.print("Broker daemon: not running \u2014 `update` will start a fresh one on the provided key.");
+    }
+  }
+  const daemonPid = deps.spawnDaemon({
+    binPath: deps.resolveBinPath(),
+    env: {
+      ...overrides.toSet,
+      MUHAVEN_BROKER_ENDPOINT: config.brokerEndpoint,
+      MUHAVEN_BACKEND_URL: effectiveEnv.MUHAVEN_BACKEND_URL,
+      MUHAVEN_DASHBOARD_URL: effectiveEnv.MUHAVEN_DASHBOARD_URL,
+      MUHAVEN_BROKER_SESSION_KEY: sessionKey
+    }
+  });
+  let ready;
+  try {
+    ready = await deps.waitForBroker({ broker });
+  } catch (err) {
+    deps.printErr(err.message);
+    deps.printErr(
+      "  hint: check that no other broker is bound to the same endpoint (muhaven-broker doctor)."
+    );
+    return 1;
+  }
+  deps.print(`Broker daemon: ready (PID ${daemonPid}, endpoint ${config.brokerEndpoint}).`);
+  try {
+    const h = await broker.hello();
+    const hasKey = h.hasSessionKey ?? true;
+    if (!hasKey) {
+      deps.printErr(
+        "Broker came up in READ-ONLY posture \u2014 the session key did not reach the daemon, so it cannot sign. Stop it (muhaven-broker stop) and retry."
+      );
+      return 1;
+    }
+    if (h.sessionKeyAddress) deps.print(`Broker signer: ${h.sessionKeyAddress}`);
+  } catch {
+  }
+  if (flags.skipLogin) {
+    deps.print("Login: skipped per --skip-login.");
+  } else if (ready.hasJwt) {
+    deps.print("Login: skipped \u2014 JWT already in keystore (reused).");
+  } else {
+    const loginArgv = [];
+    if (flags.noLaunchBrowser) loginArgv.push("--no-launch-browser");
+    if (flags.brokerEndpoint) loginArgv.push("--broker-endpoint", flags.brokerEndpoint);
+    if (flags.backendBaseUrl) loginArgv.push("--backend-base-url", flags.backendBaseUrl);
+    if (flags.dashboardBaseUrl) loginArgv.push("--dashboard-base-url", flags.dashboardBaseUrl);
+    const code = await withSeededLoginEnv(effectiveEnv, () => deps.runLogin(loginArgv));
+    if (code !== 0) {
+      deps.printErr(
+        "Login step failed \u2014 the daemon is running on the new key; re-run `muhaven-broker login` to retry."
+      );
+      return code;
+    }
+  }
+  deps.print("");
+  deps.print("================================");
+  deps.print(mode === "start" ? "Broker started." : "Session key rotated.");
+  deps.print(`  Daemon PID : ${daemonPid}`);
+  const killCmd = deps.platformId === "win32" ? `Stop-Process -Id ${daemonPid}` : `kill ${daemonPid}`;
+  deps.print(`  Stop daemon: ${killCmd}   (or: muhaven-broker stop)`);
+  deps.print(`  Endpoint   : ${config.brokerEndpoint}`);
+  deps.print("  Rotate key : muhaven-broker update --session <new-key>");
+  deps.print("================================");
+  return 0;
+}
+
 // src/broker/cli.ts
 function print(line) {
   process.stdout.write(line + "\n");
@@ -2774,6 +3537,11 @@ function printUsage() {
   print("                         (claude-code today; claude-desktop / cursor reserved for Wave 5)");
   print("                       [--register-scope user|project|local] scope for the host-config write");
   print("                         (default: user \u2014 every project sees the server)");
+  print("  start              Bring the daemon up on a DASHBOARD-minted session key (daemon NOT running)");
+  print("                       --session <key|->  the key (or `-` to read it from stdin); omit to be");
+  print("                         asked interactively. [--skip-login] [--no-launch-browser]");
+  print("  update             Rotate the session key on a running daemon (stop \u2192 swap \u2192 restart,");
+  print("                       reusing the existing JWT). --session <key|-> (or interactive).");
   print("  stop               Cleanly stop a running daemon (SIGTERM with SIGKILL fallback");
   print("                       after 5s). Also clears the keystore JWT as a best effort.");
   print("  login              Acquire a JWT via the device-code flow + store in keystore");
@@ -2785,7 +3553,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.2.9";
+    return "0.4.0";
   }
 }
 function printVersion() {
@@ -2821,6 +3589,66 @@ function defaultShellOut(cmd, argv) {
     });
   });
 }
+function stdinIsTty() {
+  return process.stdin.isTTY === true;
+}
+function promptYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      resolve(a === "" || a === "y" || a === "yes");
+    });
+  });
+}
+function promptSecret(question) {
+  return new Promise((resolve) => {
+    process.stdout.write(`${question.trimEnd()} (input hidden)
+`);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const rlAny = rl;
+    rlAny._writeToOutput = () => {
+    };
+    rl.question("", (answer) => {
+      rl.close();
+      process.stdout.write("\n");
+      resolve(answer);
+    });
+  });
+}
+async function readStdinAll() {
+  if (process.stdin.isTTY) return "";
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function makeSessionPromptDeps() {
+  return {
+    isTty: stdinIsTty(),
+    readStdinAll,
+    promptYesNo,
+    promptSecret
+  };
+}
+function makeStopDeps(clearJwtOnStop, override) {
+  const resolved = override ?? (() => {
+    const config = loadMcpConfig();
+    return { endpoint: config.brokerEndpoint, brokerTimeoutMs: config.brokerTimeoutMs };
+  })();
+  return {
+    print,
+    printErr,
+    newBrokerClient: (endpoint, timeoutMs) => new BrokerClient({ endpoint, timeoutMs }),
+    killProcess: defaultKillProcess,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    endpoint: resolved.endpoint,
+    brokerTimeoutMs: resolved.brokerTimeoutMs,
+    clearJwtOnStop
+  };
+}
 async function runSetup2(argv) {
   const deps = {
     print,
@@ -2835,22 +3663,35 @@ async function runSetup2(argv) {
     env: process.env,
     platformId: process.platform,
     osRelease: release(),
-    shellOut: defaultShellOut
+    shellOut: defaultShellOut,
+    sessionInput: makeSessionPromptDeps()
   };
   return runSetup(argv, deps);
 }
 async function runStop2() {
-  const config = loadMcpConfig();
-  const deps = {
+  return runStop(makeStopDeps(true));
+}
+function makeBringUpDeps() {
+  return {
     print,
     printErr,
     newBrokerClient: (endpoint, timeoutMs) => new BrokerClient({ endpoint, timeoutMs }),
-    killProcess: defaultKillProcess,
-    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-    endpoint: config.brokerEndpoint,
-    brokerTimeoutMs: config.brokerTimeoutMs
+    spawnDaemon,
+    waitForBroker,
+    // `update` stops the old daemon but PRESERVES the JWT (key rotation
+    // must not force a device-code re-login). Targets the resolved
+    // endpoint so a `--broker-endpoint` override stops the right daemon.
+    stopDaemon: (endpoint, brokerTimeoutMs) => runStop(makeStopDeps(false, { endpoint, brokerTimeoutMs })),
+    runLogin,
+    resolveBinPath: resolveBrokerBinPath,
+    env: process.env,
+    platformId: process.platform,
+    osRelease: release(),
+    sessionPrompt: makeSessionPromptDeps()
   };
-  return runStop(deps);
+}
+async function runStartOrUpdate(mode, argv) {
+  return runBringUp(mode, argv, makeBringUpDeps());
 }
 async function runCli(argv) {
   const [sub, ...rest] = argv;
@@ -2860,6 +3701,10 @@ async function runCli(argv) {
       return 0;
     case "setup":
       return runSetup2(rest);
+    case "start":
+      return runStartOrUpdate("start", rest);
+    case "update":
+      return runStartOrUpdate("update", rest);
     case "stop":
       return runStop2();
     case "login":
@@ -2883,4 +3728,4 @@ async function runCli(argv) {
   }
 }
 
-export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup2 as runSetup, runStop2 as runStop };
+export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup2 as runSetup, runStartOrUpdate, runStop2 as runStop };