@muhaven/mcp 0.3.0 → 0.4.1

package/dist/broker.cjs

@@ -3,6 +3,7 @@
 var os = require('os');
 var child_process = require('child_process');
 var path = require('path');
+var readline = require('readline');
 var net = require('net');
 var promises = require('fs/promises');
 var accounts = require('viem/accounts');
@@ -17,6 +18,7 @@ var DEFAULT_BROKER_MAX_BYTES = 64 * 1024;
 var DEFAULT_JWT_CACHE_TTL_SEC = 30;
 var DEFAULT_BUNDLER_TIMEOUT_MS = 2e4;
 var DEFAULT_CHAIN_ID = 421614;
+var DEFAULT_BROKER_RPC_URL = "https://sepolia-rollup.arbitrum.io/rpc";
 var DEFAULT_ENTRY_POINT_ADDRESS = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
 var ADDRESS_HEX_RE = /^0x[0-9a-fA-F]{40}$/;
 function defaultBrokerEndpoint() {
@@ -162,8 +164,8 @@ 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(
+  const chainRpcUrlRaw = readEnv("MUHAVEN_BROKER_RPC_URL", env) ?? readEnv("MUHAVEN_BUNDLER_URL", env) ?? DEFAULT_BROKER_RPC_URL;
+  const chainRpcUrl = resolvePublicUrlEnv(
     "MUHAVEN_BROKER_RPC_URL",
     chainRpcUrlRaw,
     chainRpcUrlRaw
@@ -2366,6 +2368,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",
@@ -2453,6 +2512,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;
@@ -2490,6 +2569,7 @@ function parseSetupFlags(argv) {
   let brokerEndpoint;
   let backendBaseUrl;
   let dashboardBaseUrl;
+  let brokerRpcUrl;
   let skipLogin = false;
   const register = [];
   let registerScope = "user";
@@ -2501,6 +2581,7 @@ function parseSetupFlags(argv) {
     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 if (a === "--broker-rpc-url" && i + 1 < argv.length) brokerRpcUrl = argv[++i];
     else if (a === "--register" && i + 1 < argv.length) {
       const value = argv[++i];
       for (const raw of value.split(",")) {
@@ -2531,6 +2612,7 @@ function parseSetupFlags(argv) {
     brokerEndpoint,
     backendBaseUrl,
     dashboardBaseUrl,
+    brokerRpcUrl,
     skipLogin,
     register,
     registerScope
@@ -2654,7 +2736,7 @@ async function runSetup(argv, deps) {
   } catch (err) {
     deps.printErr(`error: ${err.message}`);
     deps.printErr(
-      "usage: muhaven-broker setup [--foreground|-f] [--no-launch-browser] [--skip-login]\n                            [--broker-endpoint PATH] [--backend-base-url URL]\n                            [--dashboard-base-url URL]\n                            [--register HOST[,HOST...]] [--register-scope user|project|local]"
+      "usage: muhaven-broker setup [--foreground|-f] [--no-launch-browser] [--skip-login]\n                            [--broker-endpoint PATH] [--backend-base-url URL]\n                            [--dashboard-base-url URL] [--broker-rpc-url URL]\n                            [--register HOST[,HOST...]] [--register-scope user|project|local]"
     );
     return 2;
   }
@@ -2679,6 +2761,13 @@ async function runSetup(argv, deps) {
       return 2;
     }
   }
+  if (flags.brokerRpcUrl) {
+    const err = validateHttpUrlFlag("--broker-rpc-url", flags.brokerRpcUrl);
+    if (err) {
+      deps.printErr(`error: ${err}`);
+      return 2;
+    }
+  }
   const overrides = applyEnvDefaults({
     env: deps.env,
     platformId: deps.platformId,
@@ -2694,6 +2783,7 @@ async function runSetup(argv, deps) {
   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;
+  if (flags.brokerRpcUrl) effectiveEnv.MUHAVEN_BROKER_RPC_URL = flags.brokerRpcUrl;
   for (const name of overrides.preserved) {
     deps.print(`Env preserved: ${name} (set in your shell)`);
   }
@@ -2702,12 +2792,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) {
@@ -2756,7 +2866,11 @@ async function runSetup(argv, deps) {
         MUHAVEN_BROKER_ENDPOINT: config.brokerEndpoint,
         MUHAVEN_BACKEND_URL: effectiveEnv.MUHAVEN_BACKEND_URL,
         MUHAVEN_DASHBOARD_URL: effectiveEnv.MUHAVEN_DASHBOARD_URL,
-        MUHAVEN_BROKER_SESSION_KEY: sessionKey
+        MUHAVEN_BROKER_SESSION_KEY: sessionKey,
+        // Forward the chain RPC URL only when resolved (flag or shell env);
+        // absent → the daemon's loadBrokerConfig applies the public Arb
+        // Sepolia default.
+        ...effectiveEnv.MUHAVEN_BROKER_RPC_URL ? { MUHAVEN_BROKER_RPC_URL: effectiveEnv.MUHAVEN_BROKER_RPC_URL } : {}
       }
     });
     try {
@@ -2791,21 +2905,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."
@@ -2889,13 +2989,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) {
@@ -2953,6 +3055,212 @@ 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;
+  let brokerRpcUrl;
+  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 if (a === "--broker-rpc-url" && i + 1 < argv.length) brokerRpcUrl = argv[++i];
+    else throw new Error(`unknown flag: ${a}`);
+  }
+  return {
+    session,
+    noLaunchBrowser,
+    skipLogin,
+    brokerEndpoint,
+    backendBaseUrl,
+    dashboardBaseUrl,
+    brokerRpcUrl
+  };
+}
+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] [--broker-rpc-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;
+    }
+  }
+  if (flags.brokerRpcUrl) {
+    const e = validateHttpUrlFlag("--broker-rpc-url", flags.brokerRpcUrl);
+    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;
+  if (flags.brokerRpcUrl) effectiveEnv.MUHAVEN_BROKER_RPC_URL = flags.brokerRpcUrl;
+  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,
+      // Forward the chain RPC URL only when resolved (flag or shell env).
+      // When absent, the daemon's loadBrokerConfig applies the public
+      // Arb Sepolia default — no need to inject it here.
+      ...effectiveEnv.MUHAVEN_BROKER_RPC_URL ? { MUHAVEN_BROKER_RPC_URL: effectiveEnv.MUHAVEN_BROKER_RPC_URL } : {}
+    }
+  });
+  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");
@@ -3265,6 +3573,13 @@ 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("                       [--broker-rpc-url URL] chain RPC for Path D (default: public Arb Sepolia)");
+  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("                       [--broker-rpc-url URL] override the daemon chain RPC for Path D");
   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");
@@ -3276,7 +3591,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.3.0";
+    return "0.4.1";
   }
 }
 function printVersion() {
@@ -3312,6 +3627,66 @@ function defaultShellOut(cmd, argv) {
     });
   });
 }
+function stdinIsTty() {
+  return process.stdin.isTTY === true;
+}
+function promptYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = readline.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 = readline.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,
@@ -3326,22 +3701,35 @@ async function runSetup2(argv) {
     env: process.env,
     platformId: process.platform,
     osRelease: os.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: os.release(),
+    sessionPrompt: makeSessionPromptDeps()
   };
-  return runStop(deps);
+}
+async function runStartOrUpdate(mode, argv) {
+  return runBringUp(mode, argv, makeBringUpDeps());
 }
 async function runCli(argv) {
   const [sub, ...rest] = argv;
@@ -3351,6 +3739,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":
@@ -3381,4 +3773,5 @@ exports.runDoctor = runDoctor;
 exports.runLogin = runLogin;
 exports.runLogout = runLogout;
 exports.runSetup = runSetup2;
+exports.runStartOrUpdate = runStartOrUpdate;
 exports.runStop = runStop2;

package/dist/broker.d.cts

@@ -1,3 +1,30 @@
+/**
+ * `muhaven-broker start` / `muhaven-broker update` — install a
+ * DASHBOARD-minted Scoped session key onto the broker daemon in one shot.
+ *
+ * Wave 5 Option D OPEN-D (2026-05-24). Replaces the manual last mile after
+ * a dashboard mint / revoke:
+ *
+ *   start  — bring the daemon UP on a provided key (daemon NOT running).
+ *   update — ROTATE the key on a (possibly) running daemon: stop → swap →
+ *            restart → REUSE the existing JWT (a key rotation must not
+ *            force a device-code re-login).
+ *
+ * Both resolve the key via the shared precedence (`--session` flag >
+ * interactive masked prompt > error — see `session-input.ts`). Both
+ * REQUIRE a key (unlike `setup`, which self-mints on the fresh-install
+ * path). The key is injected ONLY into the spawned daemon's child env
+ * (**Option B** — operator decision 2026-05-24); it never touches disk,
+ * so the daemon (`loadBrokerConfig`) and the keystore stay unchanged.
+ *
+ * The orchestrator is pure-ish: all IO (broker IPC, daemon spawn, stop,
+ * login, prompts) is injected via `BringUpDeps` so the decision tree is
+ * unit-testable without spawning real processes — mirrors the
+ * `runSetup` / `runStop` style.
+ */
+
+type BringUpMode = 'start' | 'update';
+
 /**
  * `muhaven-broker` CLI subcommand router.
  *
@@ -8,6 +35,7 @@
  *   doctor         → environment + keystore capability report
  *   --help, -h     → usage
  */
+
 interface LoginFlags {
     noLaunchBrowser: boolean;
     brokerEndpoint?: string;
@@ -43,6 +71,8 @@ declare function runSetup(argv: readonly string[]): Promise<number>;
  * Wire `runStop` against the real BrokerClient + Node's process.kill.
  */
 declare function runStop(): Promise<number>;
+/** Wire `muhaven-broker start` / `update` against the real cli helpers. */
+declare function runStartOrUpdate(mode: BringUpMode, argv: readonly string[]): Promise<number>;
 declare function runCli(argv: readonly string[]): Promise<number>;
 
-export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup, runStop };
+export { getBrokerPackageVersion, parseLoginFlags, runCli, runDoctor, runLogin, runLogout, runSetup, runStartOrUpdate, runStop };