premanmcp 0.10.6 → 0.11.0

package/bin/connect.js

@@ -1,1570 +1,70 @@
 /**
  * `preman connect` — pick a coding agent and get connected, in one command.
  *
- * Replaces the hand-edited MCP config: the user picks Cursor / Claude Code /
- * Codex from a list, PreMan logs them in if needed, writes that agent's config
- * itself, and binds the connection to their account with a pair code.
+ * This file is the command itself: preflight, the order the steps run in, and
+ * the ladder that gets the first PreMan call to happen. The parts it orchestrates
+ * live next door, because each one grew its own reasons to be careful and reading
+ * them interleaved stopped being possible at around a thousand lines:
  *
- * Optionally captures a cloud-dispatch credential in the same pass so PreMan can
- * start agent runs for them later (SCRUM-124). That step is always skippable and
- * never fails the connect.
+ *   connect/agents.js    which agent, and how it is asked
+ *   connect/configs.js   writing each agent's config, and proving it landed
+ *   connect/pairing.js   pair codes and the credential behind them
+ *   connect/checkin.js   self-test, agent run, terminal opening, waiting
+ *   connect/guide.js     endpoints, first test, runner, desktop, integrations, hook
+ *   connect/dispatch.js  the cloud-dispatch credential
+ *
+ * Everything those modules export is re-exported at the bottom, so `cli.js` and
+ * the smoke suites keep importing `bin/connect.js` and cannot tell this changed.
  */
 
-import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { existsSync } from "node:fs";
 
-import { callTool as callPremanTool, printTestSummary } from "./api_tools.js";
-import { installDesktopCommand } from "./desktop.js";
-import { installHook, hookStatus } from "./hook.js";
-import { MARK, awsCommand, githubCommand, slackCommand } from "./integrations.js";
-import {
-  confirmRunnerOnline,
-  pairingIsLive,
-  readRunnerState,
-  registerRunner,
-  runnerIsAlive,
-  startBackground,
-} from "./runner.js";
 import {
   apiKeyIsExplicit,
-  assertOk,
   authenticateTerminal,
   backendUrl,
   buildServerConfig,
-  callBackendJson,
-  clearStoredCredentials,
   cliInvocation,
-  frontendUrl,
   hasKeyAvailable,
-  LAUNCHER_ARGS,
-  LAUNCHER_COMMAND,
   makeArgs,
+  onPath,
   pathPremanOwner,
-  promptSecret,
-  promptText,
-  readJsonFile,
   resolveApiKey,
-  writeJsonFile,
 } from "./shared.js";
-
-const EXIT_USAGE = 2;
-
-class ConnectError extends Error {
-  constructor(message, exitCode = 1) {
-    super(message);
-    this.exitCode = exitCode;
-  }
-}
-
-/**
- * Supported agents. `id` matches the backend's normalize_agent() vocabulary so
- * the link record and this CLI cannot disagree about who is connected.
- */
-const AGENTS = [
-  {
-    id: "cursor",
-    label: "Cursor",
-    aliases: ["cursor"],
-    dispatch: {
-      credential: "Cursor API key",
-      needsRoutine: false,
-      source: "cursor.com/dashboard → Integrations → API Keys",
-    },
-    snippetHint: "merge into ~/.cursor/mcp.json",
-    restartHint: 'Fully quit and reopen Cursor, then Settings → MCP → toggle "preman" off and on.',
-  },
-  {
-    id: "claude_code",
-    label: "Claude Code",
-    aliases: ["claude", "claude-code", "claude_code", "claudecode"],
-    dispatch: {
-      credential: "Claude Code routine token",
-      needsRoutine: true,
-      // Named explicitly because "Claude Code routine token" reads like an
-      // Anthropic API key, which is a different credential from a different page.
-      source: "claude.ai/code/routines → your routine → Add API trigger",
-    },
-    snippetHint: "run:",
-    restartHint: 'Start a new Claude Code session and run `claude mcp list` — "preman" should be listed.',
-  },
-  {
-    id: "codex",
-    label: "Codex",
-    aliases: ["codex", "openai-codex", "openai_codex"],
-    dispatch: null, // No public fire API; stays on the copy-paste path.
-    snippetHint: "append to ~/.codex/config.toml",
-    restartHint: "Restart Codex so it re-reads its config.toml.",
-  },
-];
-
-function findAgent(value) {
-  const raw = String(value || "").trim().toLowerCase().replace(/\s+/g, "-");
-  return AGENTS.find((a) => a.id === raw || a.aliases.includes(raw)) || null;
-}
-
-function onPath(binary) {
-  const probe = spawnSync(process.platform === "win32" ? "where" : "which", [binary], {
-    stdio: "ignore",
-  });
-  return probe.status === 0;
-}
-
-/**
- * Why this agent's CLI cannot run unattended right now, or "".
- *
- * Installed is not the same as usable. `cursor-agent` sits on PATH and exits 1
- * on every `-p` run until someone signs in, which surfaced as "Cursor did not
- * register any endpoints" and sent people looking at PreMan for an hour. Only
- * Cursor is probed because only its CLI has a cheap non-interactive status
- * subcommand; the others are diagnosed from their own output when they fail.
- */
-export function agentBlocker(agentId) {
-  if (agentId !== "cursor") return "";
-  const probe = spawnSync("cursor-agent", ["status"], {
-    encoding: "utf8",
-    timeout: 15000,
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  const text = `${probe.stdout || ""}${probe.stderr || ""}`;
-  if (/not logged in|not authenticated|no active session/i.test(text)) {
-    return "cursor-agent is installed but not signed in — run `cursor-agent login`";
-  }
-  return "";
-}
-
-/** Best guess at which agent this machine actually uses, for the default pick. */
-function detectAgents() {
-  const home = os.homedir();
-  return {
-    cursor: existsSync(path.join(home, ".cursor")) || Boolean(process.env.CURSOR_TRACE_ID),
-    claude_code: onPath("claude") || existsSync(path.join(home, ".claude.json")),
-    codex: onPath("codex") || existsSync(process.env.CODEX_HOME || path.join(home, ".codex")),
-  };
-}
-
-/**
- * The agent whose session this command is running inside, if any.
- *
- * A better default than "first one installed": someone who types this into an
- * agent's terminal almost always means that agent, and on a machine with all
- * three installed the detected-order default is usually wrong.
- */
-export function runningInside(env = process.env) {
-  if (env.CLAUDECODE || env.CLAUDE_CODE) return "claude_code";
-  if (env.CURSOR_TRACE_ID) return "cursor";
-  return "";
-}
-
-/** Is PreMan's MCP server already written into this agent's config? */
-function agentIsLinked(agentId, serverName = "preman") {
-  try {
-    const home = os.homedir();
-    if (agentId === "cursor") {
-      return Boolean(readJsonFile(path.join(home, ".cursor", "mcp.json")).mcpServers?.[serverName]);
-    }
-    if (agentId === "claude_code") {
-      return Boolean(readJsonFile(path.join(home, ".claude.json")).mcpServers?.[serverName]);
-    }
-    if (agentId === "codex") {
-      const file = path.join(process.env.CODEX_HOME || path.join(home, ".codex"), "config.toml");
-      return existsSync(file) && readFileSync(file, "utf8").includes(`[mcp_servers.${serverName}]`);
-    }
-  } catch {
-    // An unreadable config is not an answer; fall through to the other signals.
-  }
-  return false;
-}
-
-/**
- * Which agent this machine should pair as, or "" when only a person can say.
- *
- * Pairing needs an agent id, and demanding `--agent` for it turned "start the
- * runner" into a command someone had to be told twice. The signals are ordered
- * by how much they actually know: the session we are inside, then the agent
- * PreMan is already configured in, then the only one installed. Asking is the
- * last resort rather than the first, and a machine with no terminal to ask in
- * gets "" so the caller can fail with a sentence instead of hanging on a prompt.
- */
-export async function resolveAgentForPairing({ interactive = Boolean(process.stdin.isTTY) } = {}) {
-  const inside = runningInside();
-  if (inside) return inside;
-
-  const linked = AGENTS.filter((agent) => agentIsLinked(agent.id));
-  if (linked.length === 1) return linked[0].id;
-
-  const detected = detectAgents();
-  const present = AGENTS.filter((agent) => detected[agent.id]);
-  if (present.length === 1) return present[0].id;
-
-  if (!interactive) return "";
-  const picked = await promptAgentChoice(detected);
-  return picked?.id || "";
-}
-
-async function promptAgentChoice(detected, insideId = runningInside()) {
-  process.stdout.write("Which coding agent?\n");
-  AGENTS.forEach((agent, index) => {
-    let mark = "";
-    if (agent.id === insideId) mark = "  (this session)";
-    else if (detected[agent.id]) mark = "  (detected)";
-    process.stdout.write(`  ${index + 1}. ${agent.label}${mark}\n`);
-  });
-
-  const inside = AGENTS.findIndex((a) => a.id === insideId);
-  const defaultIndex =
-    inside >= 0
-      ? inside
-      : Math.max(
-          0,
-          AGENTS.findIndex((a) => detected[a.id])
-        );
-  const answer = await promptText(`Pick [${defaultIndex + 1}]: `);
-  if (!answer) return AGENTS[defaultIndex];
-
-  const byNumber = Number.parseInt(answer, 10);
-  if (Number.isInteger(byNumber) && byNumber >= 1 && byNumber <= AGENTS.length) {
-    return AGENTS[byNumber - 1];
-  }
-  const byName = findAgent(answer);
-  if (byName) return byName;
-  throw new ConnectError(`Not a valid choice: ${answer}`, EXIT_USAGE);
-}
-
-// ── Config writers ──────────────────────────────────────────────────────
-
-function cursorConfigPath(projectInstall) {
-  return projectInstall
-    ? path.join(process.cwd(), ".cursor", "mcp.json")
-    : path.join(os.homedir(), ".cursor", "mcp.json");
-}
-
-export function writeCursorConfig({ serverName, serverConfig, projectInstall }) {
-  const configPath = cursorConfigPath(projectInstall);
-  const config = { ...readJsonFile(configPath) };
-  config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
-  writeJsonFile(configPath, config);
-  return { path: configPath, how: "wrote" };
-}
-
-/** The `claude mcp add` invocation, shared by the writer and the printed fallback. */
-export function claudeMcpAddArgs(serverName, serverConfig, projectInstall) {
-  const envArgs = Object.entries(serverConfig.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
-  return [
-    "mcp",
-    "add",
-    serverName,
-    "--scope",
-    projectInstall ? "project" : "user",
-    ...envArgs,
-    "--",
-    serverConfig.command,
-    ...serverConfig.args,
-  ];
-}
-
-/**
- * Claude Code owns ~/.claude.json, so prefer its own CLI. Fall back to writing
- * the config directly when `claude` is not installed — a user can connect before
- * installing the agent.
- */
-export function writeClaudeConfig({ serverName, serverConfig, projectInstall }) {
-  if (onPath("claude")) {
-    const args = claudeMcpAddArgs(serverName, serverConfig, projectInstall);
-    try {
-      execFileSync("claude", args, { stdio: "pipe" });
-      return { path: projectInstall ? ".mcp.json" : "Claude Code user config", how: "registered via claude mcp add" };
-    } catch (error) {
-      const detail = error?.stderr?.toString().trim() || error.message;
-      process.stdout.write(`Note: claude mcp add failed (${detail}); writing the config directly.\n`);
-    }
-  }
-
-  if (projectInstall) {
-    const configPath = path.join(process.cwd(), ".mcp.json");
-    const config = { ...readJsonFile(configPath) };
-    config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
-    writeJsonFile(configPath, config);
-    return { path: configPath, how: "wrote" };
-  }
-
-  // Merge only mcpServers: the user config holds a lot of unrelated state.
-  // CLAUDE_CONFIG_DIR relocates that file, and writing to ~ when it is set
-  // produces a config Claude Code never reads.
-  const configPath = path.join(process.env.CLAUDE_CONFIG_DIR || os.homedir(), ".claude.json");
-  const config = { ...readJsonFile(configPath) };
-  config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
-  writeJsonFile(configPath, config);
-  return { path: configPath, how: "wrote" };
-}
-
-/**
- * Render the `[mcp_servers.<name>]` block for Codex's TOML config. Only strings
- * and string arrays appear here, so a hand-rolled writer is enough — no TOML
- * dependency for one fixed shape.
- */
-export function renderCodexToml(serverName, serverConfig) {
-  const str = (value) => JSON.stringify(String(value));
-  const lines = [
-    `[mcp_servers.${serverName}]`,
-    `command = ${str(serverConfig.command)}`,
-    `args = [${serverConfig.args.map(str).join(", ")}]`,
-  ];
-  const env = Object.entries(serverConfig.env);
-  if (env.length) {
-    lines.push("", `[mcp_servers.${serverName}.env]`);
-    for (const [key, value] of env) lines.push(`${key} = ${str(value)}`);
-  }
-  return `${lines.join("\n")}\n`;
-}
-
-/** Replace an existing preman block, or append a new one, leaving the rest alone. */
-export function upsertCodexToml(existing, serverName, block) {
-  const header = new RegExp(`^\\[mcp_servers\\.${serverName}(\\.|\\])`, "m");
-  if (!header.test(existing)) {
-    const separator = existing.trim() ? "\n" : "";
-    return `${existing.trimEnd()}${separator}\n${block}`;
-  }
-
-  const lines = existing.split("\n");
-  const out = [];
-  let skipping = false;
-  for (const line of lines) {
-    const isOurHeader = new RegExp(`^\\[mcp_servers\\.${serverName}(\\.|\\])`).test(line);
-    if (isOurHeader) {
-      skipping = true;
-      continue;
-    }
-    if (skipping && /^\[/.test(line) && !isOurHeader) skipping = false;
-    if (!skipping) out.push(line);
-  }
-  return `${out.join("\n").trimEnd()}\n\n${block}`;
-}
-
-export function writeCodexConfig({ serverName, serverConfig }) {
-  const configPath = path.join(
-    process.env.CODEX_HOME || path.join(os.homedir(), ".codex"),
-    "config.toml"
-  );
-  const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
-  const next = upsertCodexToml(existing, serverName, renderCodexToml(serverName, serverConfig));
-  mkdirSync(path.dirname(configPath), { recursive: true });
-  writeFileSync(configPath, next, { mode: 0o600 });
-  chmodSync(configPath, 0o600); // mode above is ignored for an existing file
-  return { path: configPath, how: "wrote" };
-}
-
-const WRITERS = {
-  cursor: writeCursorConfig,
-  claude_code: writeClaudeConfig,
-  codex: writeCodexConfig,
-};
-
-// ── Copy-paste fallbacks ────────────────────────────────────────────────
-
-/** Quote only what a shell would otherwise mangle, so the line stays readable. */
-function shellQuote(value) {
-  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
-
-/** What a user would paste by hand to get exactly what the writer would have written. */
-export function renderAgentSnippet(agentId, serverName, serverConfig, { projectInstall = false } = {}) {
-  if (agentId === "codex") return renderCodexToml(serverName, serverConfig);
-  if (agentId === "claude_code") {
-    const args = claudeMcpAddArgs(serverName, serverConfig, projectInstall);
-    return `claude ${args.map(shellQuote).join(" ")}\n`;
-  }
-  return `${JSON.stringify({ mcpServers: { [serverName]: serverConfig } }, null, 2)}\n`;
-}
-
-/** Every agent's snippet, for when we could not pick one for the user. */
-export function renderAllAgentSnippets(args, serverName, { projectInstall = false } = {}) {
-  // Build config WITHOUT resolved API key to avoid leaking secrets in CI logs.
-  // Users must supply --api-key or set PREMAN_API_KEY separately.
-  const env = {
-    PREMAN_BACKEND: backendUrl(args),
-    PREMAN_FRONTEND: frontendUrl(args),
-  };
-  const serverConfig = {
-    command: LAUNCHER_COMMAND,
-    args: [...LAUNCHER_ARGS],
-    env,
-  };
-
-
-  return AGENTS.map((agent) => {
-    // Adjust hint based on projectInstall, matching verifyWrittenConfig logic
-    let hint = agent.snippetHint;
-    if (agent.id === "cursor" && projectInstall) {
-      hint = "merge into .cursor/mcp.json";
-    } else if (agent.id === "claude_code") {
-      hint = projectInstall ? "run (with --scope project):" : "run:";
-    }
-    return `# ${agent.label} — ${hint}\n` + renderAgentSnippet(agent.id, serverName, serverConfig, { projectInstall });
-  }).join("\n");
-}
-
-// ── Post-write validation ───────────────────────────────────────────────
-
-/** The lines belonging to our `[mcp_servers.<name>]` block, or null if absent. */
-function codexBlockLines(text, serverName) {
-  const lines = text.split("\n");
-  const start = lines.findIndex((line) => line.trim() === `[mcp_servers.${serverName}]`);
-  if (start === -1) return null;
-  const block = [];
-  for (let i = start + 1; i < lines.length; i += 1) {
-    const line = lines[i];
-    if (/^\[/.test(line) && !line.startsWith(`[mcp_servers.${serverName}.`)) break;
-    block.push(line);
-  }
-  return block;
-}
-
-/**
- * Read back what we just wrote, so a silently-failed write is not reported as a
- * success. Proves the entry is on disk (or that Claude Code knows about it) —
- * whether the agent has actually loaded it is only ever proven by a check-in.
- *
- * Never throws: a verification that cannot run must not fail the connect. An
- * unreadable state reports "unknown" and stays quiet, because a wrong warning
- * costs more trust than a missing one.
- */
-export function verifyWrittenConfig(agent, { serverName, written }) {
-  try {
-    if (agent.id === "codex") {
-      const text = written.path && existsSync(written.path) ? readFileSync(written.path, "utf8") : "";
-      const block = codexBlockLines(text, serverName);
-      if (!block) {
-        return { status: "mismatch", detail: `no [mcp_servers.${serverName}] block in ${written.path}` };
-      }
-      if (!block.some((line) => line.trim() === `command = "${LAUNCHER_COMMAND}"`)) {
-        return {
-          status: "mismatch",
-          detail: `${written.path} does not launch ${LAUNCHER_COMMAND}`,
-        };
-      }
-      return { status: "verified" };
-    }
-
-    // Claude Code registered the server itself — ask its CLI what it ended up with.
-    if (agent.id === "claude_code" && written.how !== "wrote") {
-      const probe = spawnSync("claude", ["mcp", "get", serverName], { stdio: "ignore" });
-      if (probe.error) return { status: "unknown", detail: "could not run claude" };
-      return probe.status === 0
-        ? { status: "verified" }
-        : { status: "mismatch", detail: `claude mcp get ${serverName} did not find the server` };
-    }
-
-    const entry = readJsonFile(written.path).mcpServers?.[serverName];
-    if (!entry) return { status: "mismatch", detail: `${serverName} is missing from ${written.path}` };
-    if (entry.command !== LAUNCHER_COMMAND) {
-      return {
-        status: "mismatch",
-        detail: `${written.path} does not launch ${LAUNCHER_COMMAND}`,
-      };
-    }
-    return { status: "verified" };
-  } catch (error) {
-    return { status: "unknown", detail: error.message };
-  }
-}
-
-// ── Pairing ─────────────────────────────────────────────────────────────
-
-/**
- * Mint the pair code, distinguishing "could not reach it" from "this key is dead".
- *
- * 401 is the backend saying the key is invalid or revoked, which is the one
- * failure the caller must not shrug off: every other outcome still leaves a
- * usable config, but writing a revoked key into an agent's config produces a
- * setup that looks connected and fails on every call.
- */
-async function startPairing(args, agent, apiKey) {
-  const result = await callBackendJson(args, "PUT", "/workbench/coding-agent", {
-    token: apiKey,
-    json: { agent: agent.id, project_path: process.cwd(), start_pairing: true },
-  });
-  if (result.status_code === 401) return { pairCode: "", stale: true };
-  if (!result.ok) {
-    process.stdout.write(
-      `Note: could not start pairing (${result.status_code}); the config still works, ` +
-        "your agent will link on its first PreMan call.\n"
-    );
-    return { pairCode: "", stale: false };
-  }
-  return { pairCode: String(result.pair_code || ""), stale: false };
-}
-
-/**
- * The --no-pair stand-in for the auth check pairing performs implicitly.
- *
- * Declining a pair code should not also decline noticing the key is dead,
- * otherwise this flag writes exactly the broken config pairing would catch.
- */
-async function verifyKey(args, apiKey) {
-  const result = await callBackendJson(args, "GET", "/auth/me", { token: apiKey });
-  return { pairCode: "", stale: result.status_code === 401 };
-}
-
-/** Whichever of the two ways to learn the backend still accepts this key. */
-async function checkKeyAndPair(args, agent, apiKey) {
-  return args.has("--no-pair")
-    ? verifyKey(args, apiKey)
-    : startPairing(args, agent, apiKey);
-}
-
-/**
- * Replace credentials the backend has rejected, and return the new key.
- *
- * Only stored credentials can be replaced here: an explicit --api-key or
- * PREMAN_API_KEY would just be re-read, so those say so and stop rather than
- * looping. Refusing to continue is deliberate — the alternative is writing a
- * key we know is dead into the agent's config.
- */
-async function refreshStaleCredentials(args) {
-  if (apiKeyIsExplicit(args)) {
-    const source = args.value("--api-key", "") ? "--api-key" : "PREMAN_API_KEY";
-    throw new ConnectError(
-      `The PreMan API key from ${source} is invalid or revoked. Create a new one in the ` +
-        `dashboard, or drop ${source} and run '${cliInvocation()} connect' to sign in.`,
-      EXIT_USAGE
-    );
-  }
-  if (args.has("--skip-login") || !process.stdin.isTTY) {
-    throw new ConnectError(
-      "Saved PreMan credentials are invalid or revoked. Run " +
-        `'${cliInvocation()} logout', then connect again to sign in.`,
-      EXIT_USAGE
-    );
-  }
-
-  process.stdout.write(
-    "\nYour saved PreMan credentials are no longer valid — the key was revoked, or the\n" +
-      "account behind it was removed. Signing you in again.\n"
-  );
-  clearStoredCredentials();
-  await authenticateTerminal(args);
-  process.stdout.write("\n");
-  return resolveApiKey(args);
-}
-
-export async function waitForConnection(
-  args,
-  apiKey,
-  {
-    intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
-    timeoutMs = Number(process.env.PREMAN_CONNECT_WAIT_MS) || 300000,
-    stopWhen = null,
-    // Called once per unsuccessful poll, so a wait measured in minutes can show
-    // that it is still a wait rather than a hang.
-    onPoll = null,
-  } = {}
-) {
-  const deadline = Date.now() + timeoutMs;
-  let interrupted = false;
-  const onInterrupt = () => {
-    interrupted = true;
-  };
-  process.on("SIGINT", onInterrupt);
-
-  try {
-    while (Date.now() < deadline && !interrupted) {
-      const status = await callBackendJson(args, "GET", "/workbench/coding-agent", {
-        token: apiKey,
-      });
-      if (status.ok && status.connected) return true;
-      if (stopWhen && stopWhen()) return false;
-      if (onPoll) onPoll();
-      await new Promise((resolve) => setTimeout(resolve, intervalMs));
-    }
-  } finally {
-    process.off("SIGINT", onInterrupt);
-  }
-  return false;
-}
-
-/** A dot per poll, and the newline that closes the run of them. */
-function pollTicker() {
-  let dots = 0;
-  return {
-    tick() {
-      dots += 1;
-      process.stdout.write(".");
-    },
-    end() {
-      if (!dots) return;
-      dots = 0;
-      process.stdout.write("\n");
-    },
-  };
-}
-
-// ── Auto check-in ───────────────────────────────────────────────────────
-
-/**
- * How to ask each agent to make one PreMan call without opening its UI.
- *
- * The link is established by the agent's first call, so anything that reaches
- * `preman_status` finishes the connect. Claude Code needs the server on its
- * allow-list because print mode refuses un-allowed MCP tools rather than
- * prompting.
- */
-export function headlessCheckIn(agent, serverName) {
-  const prompt = checkInPrompt(serverName);
-  if (agent.id === "cursor") return { bin: "cursor-agent", args: ["-p", prompt] };
-  if (agent.id === "claude_code") {
-    return { bin: "claude", args: ["-p", prompt, "--allowedTools", `mcp__${serverName}`] };
-  }
-  if (agent.id === "codex") return { bin: "codex", args: ["exec", prompt] };
-  return null;
-}
-
-function checkInPrompt(serverName) {
-  return `Call the ${serverName} MCP tool preman_status and report the result.`;
-}
-
-/**
- * How to start each agent as the session the user actually works in.
- *
- * Print mode (`-p`, `codex exec`) answers once and exits: it is a batch call, not
- * the agent anybody goes on to use, and its failures are invisible because
- * nobody is looking at it. The interactive form is the same prompt without that
- * flag — it needs a terminal of its own, which is what openInNewTerminal is for.
- */
-export function interactiveCheckIn(agent, serverName) {
-  const prompt = checkInPrompt(serverName);
-  if (agent.id === "cursor") return { bin: "cursor-agent", args: [prompt] };
-  if (agent.id === "claude_code") {
-    return { bin: "claude", args: ["--allowedTools", `mcp__${serverName}`, prompt] };
-  }
-  if (agent.id === "codex") return { bin: "codex", args: [prompt] };
-  return null;
-}
-
-/** A command line for a spec, quoted for the shell the terminal will start. */
-export function commandLine(spec) {
-  return [spec.bin, ...spec.args].map(shellQuote).join(" ");
-}
-
-/** Escape a shell line into an AppleScript string literal. */
-function appleScriptString(value) {
-  return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-
-/**
- * The terminal emulator to open a window in, or null when we know of none.
- *
- * `sync` marks the launchers that hand the work to an app and return — those
- * report their own failure through an exit code, which is worth waiting for.
- * The rest *are* the window, so they are spawned detached and outlive us.
- */
-function terminalLauncher(line) {
-  if (process.platform === "darwin") {
-    const iterm = existsSync("/Applications/iTerm.app");
-    const script = iterm
-      ? `tell application "iTerm"\nactivate\nset w to (create window with default profile)\ntell current session of w to write text ${appleScriptString(line)}\nend tell`
-      : `tell application "Terminal"\nactivate\ndo script ${appleScriptString(line)}\nend tell`;
-    return { bin: "osascript", args: ["-e", script], label: iterm ? "iTerm" : "Terminal", sync: true };
-  }
-
-  if (process.platform === "win32") {
-    return {
-      bin: "cmd.exe",
-      args: ["/c", "start", "cmd.exe", "/k", line],
-      label: "Command Prompt",
-      sync: true,
-    };
-  }
-
-  // Keep the shell alive afterwards: an agent that exits immediately would
-  // otherwise take its own error message off the screen with it.
-  const body = `${line}; exec ${process.env.SHELL || "sh"}`;
-  const candidates = [
-    { bin: "x-terminal-emulator", args: ["-e", "sh", "-c", body], label: "terminal" },
-    { bin: "gnome-terminal", args: ["--", "sh", "-c", body], label: "GNOME Terminal" },
-    { bin: "konsole", args: ["-e", "sh", "-c", body], label: "Konsole" },
-    { bin: "xterm", args: ["-e", "sh", "-c", body], label: "xterm" },
-  ];
-  return candidates.find((candidate) => onPath(candidate.bin)) || null;
-}
-
-/**
- * Open `command` in a new terminal window, best effort.
- *
- * Same contract as openUrl: never throws, and declines rather than guessing when
- * nobody is watching — `PREMAN_NO_TERMINAL` for an explicit no, and a non-TTY
- * stdout for CI, piped output and test runs. Callers fall back to a headless run.
- */
-export function openInNewTerminal(command, options = {}) {
-  const cwd = options?.cwd || process.cwd();
-  const optOut = (process.env.PREMAN_NO_TERMINAL || "").trim().toLowerCase();
-  if (optOut && !["0", "false", "no"].includes(optOut)) {
-    return { opened: false, reason: "PREMAN_NO_TERMINAL is set" };
-  }
-  if (!process.stdout.isTTY) return { opened: false, reason: "not running in a terminal" };
-
-  const launcher = terminalLauncher(`cd ${shellQuote(cwd)} && ${command}`);
-  if (!launcher) return { opened: false, reason: "no terminal emulator found" };
-
-  try {
-    if (launcher.sync) {
-      const done = spawnSync(launcher.bin, launcher.args, { stdio: "ignore", timeout: 20000 });
-      if (done.error) return { opened: false, reason: done.error.message };
-      if (done.status !== 0) {
-        return { opened: false, reason: `${launcher.bin} exited with code ${done.status}` };
-      }
-    } else {
-      const child = spawn(launcher.bin, launcher.args, { stdio: "ignore", detached: true });
-      child.unref();
-    }
-    return { opened: true, terminal: launcher.label };
-  } catch (error) {
-    return { opened: false, reason: error.message };
-  }
-}
-
-/**
- * Finish the link ourselves instead of asking the user to go restart their agent.
- *
- * The config on disk is already correct at this point; all that is missing is
- * one call from the agent, and telling someone to make it from another terminal
- * is a dead end in the one terminal they are sitting in.
- *
- * So start the agent. Interactively, in a window of its own, because that is the
- * session the user keeps: a print-mode run answers once, exits, and leaves them
- * exactly where they started. Only when no window can be opened — CI, SSH, a
- * machine with no terminal emulator — does this fall back to the headless run,
- * which still finishes the link even though nobody sees it happen.
- *
- * `cwd` is where the agent starts, and it is load-bearing rather than tidiness:
- * the MCP server reads its repo config out of the working directory, so starting
- * the agent elsewhere is how a caller escapes a directory that would otherwise
- * redirect it to a backend this key was never issued for.
- *
- * Returns `ran: false` when the agent's binary is absent or will not start, and
- * the caller falls back to the printed instructions.
- */
-export async function autoCheckIn(
-  args,
-  agent,
-  apiKey,
-  {
-    // Never outlast the connect's own wait budget: this phase is part of it, not
-    // an extra one bolted on the front.
-    timeoutMs = Math.min(
-      Number(process.env.PREMAN_AUTO_CHECKIN_MS) || 120000,
-      Number(process.env.PREMAN_CONNECT_WAIT_MS) || 300000
-    ),
-    serverName = "preman",
-    intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
-    cwd = process.cwd(),
-    onLaunch = () => {},
-    onPoll = null,
-  } = {}
-) {
-  const session = interactiveCheckIn(agent, serverName);
-  if (session && onPath(session.bin)) {
-    const { opened, terminal } = openInNewTerminal(commandLine(session), { cwd });
-    if (opened) {
-      onLaunch({ mode: "interactive", bin: session.bin, terminal });
-      // Detached, so there is no exit to watch for and no output to quote: the
-      // agent is in front of the user now, and the deadline is all that bounds
-      // this. Whoever is watching the window can Ctrl+C out of the wait.
-      const connected = await waitForConnection(args, apiKey, { intervalMs, timeoutMs, onPoll });
-      return { ran: true, connected, command: session.bin, interactive: true, terminal };
-    }
-  }
-
-  const spec = headlessCheckIn(agent, serverName);
-  if (!spec) return { ran: false, connected: false, reason: "no headless mode" };
-  if (!onPath(spec.bin)) return { ran: false, connected: false, reason: `${spec.bin} is not on PATH` };
-
-  let child;
-  try {
-    // Piped rather than ignored: an agent that runs and does not check in used to
-    // report exactly that and nothing else, which is the least useful sentence
-    // available. Its own last words usually name the cause.
-    child = spawn(spec.bin, spec.args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
-  } catch (error) {
-    return { ran: false, connected: false, reason: error.message };
-  }
-  onLaunch({ mode: "headless", bin: spec.bin });
-
-  let spawnError = null;
-  let exitedAt = 0;
-  let output = "";
-  const absorb = (chunk) => {
-    output = `${output}${chunk}`.slice(-4000);
-  };
-  child.stdout?.setEncoding("utf8");
-  child.stderr?.setEncoding("utf8");
-  child.stdout?.on("data", absorb);
-  child.stderr?.on("data", absorb);
-  child.on("error", (error) => {
-    spawnError = error;
-    exitedAt = exitedAt || Date.now();
-  });
-  child.on("exit", () => {
-    exitedAt = exitedAt || Date.now();
-  });
-
-  // The check-in can land moments after the agent's own process ends, so keep
-  // polling briefly past its exit rather than declaring failure at the edge.
-  const grace = intervalMs * 2;
-  try {
-    const connected = await waitForConnection(args, apiKey, {
-      intervalMs,
-      timeoutMs,
-      onPoll,
-      stopWhen: () => Boolean(exitedAt) && Date.now() - exitedAt > grace,
-    });
-    if (spawnError && !connected) {
-      return { ran: false, connected: false, reason: spawnError.message, output };
-    }
-    return { ran: true, connected, command: spec.bin, output };
-  } finally {
-    if (child.exitCode === null && child.signalCode === null) child.kill();
-  }
-}
-
-/** The last non-empty line of an agent's output, for a one-line diagnosis. */
-export function lastLine(output, cap = 200) {
-  const lines = String(output || "")
-    .split("\n")
-    .map((line) => line.trim())
-    .filter(Boolean);
-  return lines.length ? lines[lines.length - 1].slice(0, cap) : "";
-}
-
-// ── MCP self-test ───────────────────────────────────────────────────────
-
-/**
- * How long to give the self-test, and whether to run it at all.
- *
- * `PREMAN_SELFTEST_MS=0` turns it off for a whole process, which is what a test
- * run wants: the launcher is `npm exec premanmcp@latest`, so every case that
- * reaches this would otherwise go to the registry.
- */
-export function selfTestBudgetMs() {
-  const raw = process.env.PREMAN_SELFTEST_MS;
-  if (raw === undefined || raw === "") return 60000;
-  const parsed = Number(raw);
-  return Number.isFinite(parsed) ? parsed : 60000;
-}
-
-/**
- * Run the config we just wrote, exactly as the agent will, and call one tool.
- *
- * This is both the fastest way to finish the link and the only check that proves
- * the whole chain — launcher, package, key, backend — rather than proving the
- * file is on disk. It matters because the failure it catches is invisible
- * otherwise: a repo-local `preman-mcp.config.json` (or a stale global env) can
- * redirect the server to a backend the key was never issued for, and every
- * symptom of that points at the key.
- *
- * Speaks the two JSON-RPC calls an MCP client makes on startup. Never throws.
- */
-export async function mcpSelfTest(
-  serverConfig,
-  { timeoutMs = selfTestBudgetMs(), cwd = process.cwd() } = {}
-) {
-  if (timeoutMs <= 0) return { ok: false, reason: "self-test disabled" };
-  let child;
-  try {
-    child = spawn(serverConfig.command, serverConfig.args, {
-      cwd,
-      env: { ...process.env, ...serverConfig.env },
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-  } catch (error) {
-    return { ok: false, reason: error.message };
-  }
-
-  return new Promise((resolve) => {
-    let stdout = "";
-    let stderr = "";
-    let settled = false;
-
-    const finish = (result) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (child.exitCode === null && child.signalCode === null) child.kill();
-      resolve(result);
-    };
-
-    const timer = setTimeout(
-      () => finish({ ok: false, reason: `the MCP server did not answer within ${Math.round(timeoutMs / 1000)}s`, stderr: lastLine(stderr) }),
-      timeoutMs
-    );
-
-    const send = (message) => {
-      try {
-        child.stdin.write(`${JSON.stringify(message)}\n`);
-      } catch (error) {
-        finish({ ok: false, reason: error.message });
-      }
-    };
-
-    child.on("error", (error) => finish({ ok: false, reason: error.message }));
-    child.on("exit", (code) =>
-      finish({
-        ok: false,
-        reason: `the MCP server exited with code ${code}`,
-        stderr: lastLine(stderr),
-      })
-    );
-
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    child.stderr.on("data", (chunk) => {
-      stderr = `${stderr}${chunk}`.slice(-4000);
-    });
-    child.stdout.on("data", (chunk) => {
-      stdout += chunk;
-      let newline = stdout.indexOf("\n");
-      while (newline !== -1) {
-        const line = stdout.slice(0, newline).trim();
-        stdout = stdout.slice(newline + 1);
-        newline = stdout.indexOf("\n");
-        if (!line.startsWith("{")) continue;
-        let message;
-        try {
-          message = JSON.parse(line);
-        } catch {
-          continue;
-        }
-        if (message.id === 1) {
-          send({ jsonrpc: "2.0", method: "notifications/initialized" });
-          send({
-            jsonrpc: "2.0",
-            id: 2,
-            method: "tools/call",
-            params: { name: "preman_status", arguments: {} },
-          });
-          continue;
-        }
-        if (message.id !== 2) continue;
-        const text = message.result?.content?.[0]?.text;
-        let status = {};
-        try {
-          status = text ? JSON.parse(text) : {};
-        } catch {
-          status = { raw: text };
-        }
-        finish({ ok: !message.error, status, reason: message.error?.message || "" });
-      }
-    });
-
-    send({
-      jsonrpc: "2.0",
-      id: 1,
-      method: "initialize",
-      params: {
-        protocolVersion: "2024-11-05",
-        capabilities: {},
-        clientInfo: { name: "preman-connect-selftest", version: "1" },
-      },
-    });
-  });
-}
-
-// ── Dispatch credential (SCRUM-124) ─────────────────────────────────────
-
-async function captureDispatchCredential(args, agent, apiKey, { prompt = true } = {}) {
-  if (!agent.dispatch) return;
-  if (args.has("--skip-dispatch-credential")) return;
-
-  let secret = args.value("--dispatch-credential", "");
-  let routineId = args.value("--routine-id", "");
-
-  if (!secret) {
-    if (!prompt || !process.stdin.isTTY) return;
-    // Framed as the expected step rather than an optional aside. Without it
-    // PreMan can only suggest fixes; with it, it can run them. Presenting it as
-    // "optional, press Enter to skip" meant almost everyone skipped the thing
-    // that makes the product act rather than advise.
-    process.stdout.write(
-      `\nOptional — let PreMan start ${agent.label} runs for you, so it can apply\n` +
-        `fixes and run checks on a schedule instead of only telling you what to do.\n` +
-        `Get the token from ${agent.dispatch.source}.\n`
-    );
-    secret = await promptSecret(`Paste your ${agent.dispatch.credential} (Enter to skip): `);
-    if (!secret) {
-      process.stdout.write(
-        `Skipped. Run '${cliInvocation()} dispatch --agent ${agent.id.replace("_", "-")}' when you have the token.\n`
-      );
-      return;
-    }
-    if (agent.dispatch.needsRoutine && !routineId) {
-      routineId = await promptText("Routine id or URL: ");
-    }
-  }
-
-  if (agent.dispatch.needsRoutine && !routineId) {
-    process.stdout.write("Skipped: a routine id is required alongside the token.\n");
-    return;
-  }
-
-  const body = agent.dispatch.needsRoutine
-    ? { provider: agent.id, secret, routine_id: extractRoutineId(routineId) }
-    : { provider: agent.id, secret };
-
-  const result = await callBackendJson(args, "PUT", "/workbench/coding-agent/dispatch", {
-    token: apiKey,
-    json: body,
-  });
-
-  if (result.ok) {
-    process.stdout.write("Cloud dispatch enabled — PreMan can now start runs for you.\n");
-  } else if (result.status_code === 404 || result.status_code === 405) {
-    process.stdout.write("Note: this PreMan backend does not support cloud dispatch yet; skipped.\n");
-  } else {
-    process.stdout.write(`Note: could not save the credential (${result.status_code}); skipped.\n`);
-  }
-}
-
-export const DISPATCH_HELP = `
-Dispatch options:
-  --agent <name>              cursor | claude-code (defaults to the connected agent)
-  --dispatch-credential <t>   Cloud-dispatch token (non-interactive)
-  --routine-id <id>           Claude Code routine id, with --dispatch-credential
-  --api-key <key>             PreMan API key. If omitted, stored credentials are used
-  --backend <url>             PreMan backend URL
-`;
-
-/**
- * `preman dispatch` — store the cloud-dispatch credential on its own.
- *
- * Exists so connect never has to ask for a token mid-onboarding. Someone who
- * skipped it (or did not have it yet) comes back here instead of re-running the
- * whole connect.
- */
-export async function dispatchCommand(commandArgs) {
-  const args = makeArgs(commandArgs);
-  const apiKey = resolveApiKey(args);
-  if (!apiKey) {
-    throw new ConnectError(
-      `No PreMan credentials. Run '${cliInvocation()} connect' first, or pass --api-key pm_live_….`,
-      EXIT_USAGE
-    );
-  }
-
-  let agent = findAgent(args.value("--agent", ""));
-  if (!agent && args.value("--agent", "")) {
-    throw new ConnectError(
-      `Unknown agent: ${args.value("--agent", "")}. Use cursor or claude-code.`,
-      EXIT_USAGE
-    );
-  }
-
-  if (!agent) {
-    const current = await callBackendJson(args, "GET", "/workbench/coding-agent", { token: apiKey });
-    agent = findAgent(current.ok ? current.agent : "");
-    if (!agent) {
-      throw new ConnectError(
-        "Could not tell which agent to set up. Pass --agent cursor or --agent claude-code.",
-        EXIT_USAGE
-      );
-    }
-  }
-
-  if (!agent.dispatch) {
-    throw new ConnectError(`${agent.label} has no cloud-dispatch API yet.`, EXIT_USAGE);
-  }
-  if (!args.value("--dispatch-credential", "") && !process.stdin.isTTY) {
-    throw new ConnectError(
-      "preman dispatch needs a terminal, or --dispatch-credential <token>.",
-      EXIT_USAGE
-    );
-  }
-
-  await captureDispatchCredential(args, agent, apiKey);
-}
-
-/** Accept either a bare trig_… id or the routine URL it appears in. */
-export function extractRoutineId(value) {
-  const raw = String(value || "").trim();
-  const match = raw.match(/trig_[A-Za-z0-9]+/);
-  return match ? match[0] : raw;
-}
-
-// ── Guided first run ────────────────────────────────────────────────────
-
-const MANUAL_STEPS =
-  "  preman endpoints discover                       # brief for your agent → endpoints.json\n" +
-  "  preman endpoints setup --file endpoints.json    # register runnable requests\n" +
-  "  preman test <request-id>                        # generate + run your first scenarios\n";
-
-function nextStepsBlock(agent) {
-  return (
-    "\nNext steps:\n" +
-    `  1. Restart ${agent.label}, then ask it: "run preman_status" to finish linking.\n` +
-    `  2. ${cliInvocation()} runner start --background   # let PreMan run work here\n` +
-    `  3. ${cliInvocation()} endpoints discover          # brief for your agent → endpoints.json\n` +
-    `  4. ${cliInvocation()} hook install                # test affected endpoints on git push\n`
-  );
-}
-
-/**
- * What is left once the link is done, as commands rather than as questions.
- *
- * Connect used to run all of these itself, which bought a prompt per step and a
- * wait as long as the slowest broken one — and a link that had already succeeded
- * ended on a failed runner and a five-minute GitHub poll. Each is one command, so
- * this lists them and gets out of the way.
- */
-function whatIsLeftBlock(args) {
-  const cli = cliInvocation();
-  return (
-    "\nWhat is left:\n" +
-    `  ${cli} endpoints discover          # map this repo's endpoints\n` +
-    `  ${cli} runner start --background   # let PreMan apply fixes on this machine\n` +
-    `  ${cli} github                      # connect GitHub, or do it in the dashboard\n` +
-    `\n${cli} status reports your endpoints, last push and integrations.\n` +
-    `Watch runs at ${frontendUrl(args)}\n`
-  );
-}
-
-/**
- * Ask, or take the step's own default when nobody can answer.
- *
- * `--yes` returns the default rather than a blanket yes, which matters for
- * exactly one step: the desktop app defaults to no because it downloads a
- * hundred-odd megabytes and writes to /Applications. A blanket yes made
- * `preman connect --yes` do that unattended, which is not what anyone means by
- * "do not ask me questions" -- they get `preman install-desktop` for that.
- */
-async function confirm(question, { assumeYes = false, defaultYes = true } = {}) {
-  if (assumeYes) return defaultYes;
-  if (!process.stdin.isTTY) return false;
-  const answer = (await promptText(`${question} ${defaultYes ? "[Y/n]" : "[y/N]"}: `)).toLowerCase();
-  if (answer === "") return defaultYes;
-  return answer.startsWith("y");
-}
-
-function step(title) {
-  process.stdout.write(`\n${title}\n`);
-}
-
-/** What the account can see right now: registry rows, and the runnable subset. */
-async function endpointCounts(args) {
-  const inventory = await callPremanTool(args, "get_endpoints", {
-    include_workbench: true,
-    limit: 200,
-  });
-  const runnable = inventory.workbench_requests || [];
-  return {
-    registered: (inventory.endpoints || []).length,
-    runnable: runnable.length,
-    first: runnable[0] || null,
-  };
-}
-
-/**
- * The one-shot command that has an agent execute the discovery brief.
- *
- * Same shape as `headlessCheckIn`, with the read tools the walk needs added to
- * Claude Code's allow-list: print mode refuses anything un-allowed instead of
- * asking, so an agent given only the MCP server can call PreMan and read nothing.
- */
-export function headlessDiscovery(agent, serverName, instructions = []) {
-  const prompt = [
-    `Register this project's HTTP endpoints in PreMan using the ${serverName} MCP tools.`,
-    "Work autonomously and do not ask for confirmation.",
-    "",
-    ...instructions,
-  ].join("\n");
-  if (agent.id === "cursor") return { bin: "cursor-agent", args: ["-p", prompt] };
-  if (agent.id === "claude_code") {
-    return {
-      bin: "claude",
-      args: ["-p", prompt, "--allowedTools", `mcp__${serverName},Read,Grep,Glob`],
-    };
-  }
-  if (agent.id === "codex") return { bin: "codex", args: ["exec", prompt] };
-  return null;
-}
-
-/**
- * Get this project's endpoints into PreMan without handing anyone homework.
- *
- * Discovery is the agent's job — only it can read the repo — but "here is a brief,
- * go paste it somewhere" is the step everybody dropped out on, and the commands
- * printed after it referenced a file the user never had. So run the agent on the
- * brief and report the two numbers that matter.
- *
- * Never throws: a failed discovery must not fail the connect.
- */
-export async function discoverEndpoints(args, agent, serverName, blockedHere = "") {
-  try {
-    const before = await endpointCounts(args);
-    if (before.registered) {
-      process.stdout.write(
-        `${MARK.ok()} ${before.registered} endpoint(s) · ${before.runnable} runnable\n`
-      );
-      return before;
-    }
-
-    const brief = await callPremanTool(args, "discover_endpoints_from_codebase", { base_path: "." });
-    const spec = headlessDiscovery(agent, serverName, brief.instructions || []);
-    // Discovery has to read *this* repo, so it cannot be moved out of a directory
-    // that redirects it the way the check-in was — it can only be skipped, before
-    // it spends ten minutes proving what the self-test already found out.
-    const blocker = blockedHere || (spec && onPath(spec.bin) ? agentBlocker(agent.id) : "");
-    if (!spec || !onPath(spec.bin) || blocker) {
-      // Say why before printing homework: "here is a brief" reads as PreMan not
-      // working, when the actual answer is one login away.
-      if (blocker) process.stdout.write(`${MARK.skip()} ${blocker}\n`);
-      for (const line of brief.instructions || []) process.stdout.write(`${line}\n`);
-      process.stdout.write(`\nHand this brief to ${agent.label}, then run:\n${MANUAL_STEPS}`);
-      return before;
-    }
-
-    process.stdout.write(`Asking ${agent.label} to map this codebase…\n`);
-    const timeoutMs = Number(process.env.PREMAN_DISCOVER_MS) || 600000;
-    const outcome = await runAgentOnce(spec, timeoutMs);
-    const after = await endpointCounts(args);
-
-    if (!after.registered) {
-      // Both halves: the exit code says the run failed, the agent's own last line
-      // says why, and either one alone has sent someone down the wrong path.
-      const why =
-        [outcome.reason, lastLine(outcome.output)].filter(Boolean).join(" · ") ||
-        "it registered nothing";
-      process.stdout.write(
-        `${MARK.fail()} ${agent.label} did not register any endpoints (${why}).\n` +
-          `   Run it yourself: ${cliInvocation()} endpoints discover\n`
-      );
-      return after;
-    }
-    process.stdout.write(
-      `${MARK.ok()} ${after.registered} endpoint(s) · ${after.runnable} runnable\n`
-    );
-    return after;
-  } catch (error) {
-    process.stdout.write(`${MARK.fail()} Could not read your endpoints: ${error.message}\n`);
-    return { registered: 0, runnable: 0, first: null };
-  }
-}
-
-/** Run one bounded, non-interactive agent invocation and keep its tail. */
-async function runAgentOnce(spec, timeoutMs) {
-  return new Promise((resolve) => {
-    let child;
-    try {
-      child = spawn(spec.bin, spec.args, { stdio: ["ignore", "pipe", "pipe"] });
-    } catch (error) {
-      resolve({ ok: false, reason: error.message, output: "" });
-      return;
-    }
-    let output = "";
-    const absorb = (chunk) => {
-      output = `${output}${chunk}`.slice(-8000);
-    };
-    child.stdout?.setEncoding("utf8");
-    child.stderr?.setEncoding("utf8");
-    child.stdout?.on("data", absorb);
-    child.stderr?.on("data", absorb);
-
-    const timer = setTimeout(() => {
-      child.kill("SIGTERM");
-      resolve({ ok: false, reason: `timed out after ${Math.round(timeoutMs / 1000)}s`, output });
-    }, timeoutMs);
-    child.on("error", (error) => {
-      clearTimeout(timer);
-      resolve({ ok: false, reason: error.message, output });
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      resolve({
-        ok: code === 0,
-        reason: code === 0 ? "" : `${spec.bin} exited with code ${code}`,
-        output,
-      });
-    });
-  });
-}
-
-/** Generate and run scenarios against the first runnable request, if they want it. */
-async function runFirstTest(args, runnable, { assumeYes }) {
-  const label = `${runnable.method || "GET"} ${runnable.url || ""}`.trim();
-  if (!(await confirm(`Run a first test against ${label}?`, { assumeYes }))) {
-    process.stdout.write(`${MARK.skip()} Whenever you are ready: ${cliInvocation()} test ${runnable.id}\n`);
-    return;
-  }
-  try {
-    process.stdout.write("Generating scenarios…\n");
-    const result = await callPremanTool(args, "generate_endpoint_tests", {
-      target: runnable.id,
-      run: true,
-      allow_writes: false,
-      max_cases: 10,
-    });
-    printTestSummary(result);
-  } catch (error) {
-    process.stdout.write(`${MARK.fail()} Could not run the first test: ${error.message}\n`);
-  }
-}
-
-/**
- * Whether a stored pairing can still be used, rather than merely matching.
- *
- * Matching agent and path only prove the state was written for this project. The
- * token behind it can be revoked, replaced by another device, or left over from an
- * API key that no longer exists — and reusing one of those starts a daemon that
- * 401s on its first stream and exits, which reads as "the runner cannot start
- * here" when the pairing is the only thing that needed replacing.
- *
- * A backend we cannot reach answers "usable": re-pairing is for a token the
- * backend rejected, not for a network that was briefly down.
- */
-export async function runnerPairingIsUsable(args, existing, agentId, { cwd = process.cwd() } = {}) {
-  if (!existing || existing.agent !== agentId) return false;
-  if (path.resolve(String(existing.project_path || "")) !== path.resolve(cwd)) return false;
-  return pairingIsLive(args, existing);
-}
-
-/**
- * Pair this machine as a runner and leave it running.
- *
- * Without this, everything PreMan finds later is advice: it can describe a fix
- * and cannot apply one. With it, the queue has somewhere to land.
- */
-async function setUpRunner(args, agent, { assumeYes }) {
-  if (args.has("--no-runner")) return { state: "skipped" };
-  const existing = readRunnerState();
-  if (existing && runnerIsAlive()) {
-    process.stdout.write(`${MARK.ok()} Runner already running for ${existing.project_path}\n`);
-    return { state: "running" };
-  }
-  if (
-    !(await confirm(
-      `Let PreMan run ${agent.label} here when it finds something to fix?`,
-      { assumeYes }
-    ))
-  ) {
-    process.stdout.write(
-      `${MARK.skip()} Skipped. Start it later: ${cliInvocation()} runner start --background\n`
-    );
-    return { state: "skipped" };
-  }
-
-  try {
-    if (!(await runnerPairingIsUsable(args, existing, agent.id))) {
-      await registerRunner(args, { agent: agent.id, projectPath: process.cwd() });
-    }
-    const started = startBackground([]);
-    // Claiming a runner that died two seconds later is worse than saying nothing:
-    // the whole point of this step is that PreMan can act, and someone told it
-    // can will wait for fixes that no device is listening for.
-    const up = await confirmRunnerOnline(started);
-    if (up.state === "exited") {
-      process.stdout.write(
-        `${MARK.fail()} The runner exited right after starting.\n` +
-          (up.detail ? `   ${up.detail}\n` : "") +
-          `   Log: ${started.log}   Retry: ${cliInvocation()} runner start --background\n`
-      );
-      return { state: "failed", detail: up.detail };
-    }
-    process.stdout.write(
-      `${MARK.ok()} Runner ${up.state === "online" ? "online" : "starting"} (pid ${started.pid}) — PreMan can apply fixes on this machine.\n` +
-        `   Log: ${started.log}   Stop: ${cliInvocation()} runner stop\n`
-    );
-    // Paired and online still cannot run anything if the agent it dispatches to
-    // will not start, and every job would fail with the same opaque exit code.
-    const blocker = agentBlocker(agent.id);
-    if (blocker) {
-      process.stdout.write(`   ${MARK.skip()} Jobs will fail until you fix this: ${blocker}\n`);
-    }
-    return { state: "running", pid: started.pid };
-  } catch (error) {
-    process.stdout.write(
-      `${MARK.fail()} Could not start the runner: ${error.message}\n` +
-        `   Retry later: ${cliInvocation()} runner start --background\n`
-    );
-    return { state: "failed", detail: error.message };
-  }
-}
-
-/** Offer the desktop app. Optional by design — the terminal flow is complete without it. */
-async function offerDesktop(args, { assumeYes }) {
-  if (args.has("--no-desktop")) return { state: "skipped" };
-  if (process.platform !== "darwin") return { state: "unsupported" };
-  if (existsSync("/Applications/PreMan.app")) {
-    process.stdout.write(`${MARK.ok()} PreMan desktop app already installed.\n`);
-    return { state: "installed" };
-  }
-  // Default no, unlike every other step here: this one downloads a hundred-odd
-  // megabytes and writes to /Applications, which nobody should get by pressing
-  // Enter to move past a prompt.
-  if (
-    !(await confirm("Install the PreMan desktop app to watch runs and endpoints?", {
-      assumeYes,
-      defaultYes: false,
-    }))
-  ) {
-    process.stdout.write(
-      `${MARK.skip()} Skipped. Install later: ${cliInvocation()} install-desktop\n`
-    );
-    return { state: "skipped" };
-  }
-  try {
-    return await installDesktopCommand([]);
-  } catch (error) {
-    process.stdout.write(`${MARK.fail()} Desktop install failed: ${error.message}\n`);
-    return { state: "failed", detail: error.message };
-  }
-}
-
-/**
- * Which of GitHub, AWS and Slack this account already has.
- *
- * One probe per provider because each owns its own list route; a provider whose
- * route errors is reported as unknown rather than missing, so a backend hiccup
- * does not send someone through an install they already did.
- */
-export async function integrationStatus(args, apiKey) {
-  const probe = async (method, route, pick) => {
-    try {
-      const result = await callBackendJson(args, method, route, { token: apiKey });
-      if (!result.ok) return null;
-      return (pick(result) || []).length;
-    } catch {
-      return null;
-    }
-  };
-  const [github, aws, slack] = await Promise.all([
-    probe("GET", "/integrations/github", (r) => r.list || r.integrations || r.repos),
-    probe("GET", "/aws-links", (r) => r.links || r.list),
-    probe("GET", "/slack/connections", (r) => r.connections || r.list),
-  ]);
-  return { github, aws, slack };
-}
-
-/**
- * Show what is connected, and offer to finish what is not.
- *
- * Each install lives in the customer's browser session, so every one of these
- * opens a URL and polls our own API until the other side reports the connection
- * exists — the terminal picks the result up on its own, whether they finished in
- * the browser or in the desktop app.
- */
-async function connectIntegrations(args, apiKey, { assumeYes }) {
-  if (args.has("--no-integrations")) return;
-  const status = await integrationStatus(args, apiKey);
-  const providers = [
-    { key: "github", label: "GitHub", question: "Connect GitHub?", run: () => githubCommand(args) },
-    { key: "aws", label: "AWS", question: "Connect AWS?", run: () => awsCommand(args) },
-    { key: "slack", label: "Slack", question: "Connect Slack?", run: () => slackCommand(args) },
-  ];
-
-  for (const provider of providers) {
-    const count = status[provider.key];
-    if (count === null) {
-      process.stdout.write(`${MARK.skip()} ${provider.label} — could not check\n`);
-    } else if (count > 0) {
-      process.stdout.write(`${MARK.ok()} ${provider.label} connected\n`);
-    } else {
-      process.stdout.write(`${MARK.skip()} ${provider.label} not connected\n`);
-    }
-  }
-
-  for (const provider of providers) {
-    if (status[provider.key] !== 0) continue;
-    if (!(await confirm(provider.question, { assumeYes, defaultYes: false }))) continue;
-    try {
-      await provider.run();
-    } catch (error) {
-      // One provider's failure must not cost the customer the ones that worked.
-      process.stdout.write(`${MARK.fail()} Could not finish ${provider.label}: ${error.message}\n`);
-    }
-  }
-}
-
-/**
- * Install the pre-push hook, so a push is what triggers the tests.
- *
- * Not a question: testing what you just changed before it ships is the product,
- * the hook cannot block a push, and `--no-hook` / `PREMAN_SKIP_HOOK=1` are both
- * still there. Asking only produced accounts that never tested anything.
- */
-async function setUpPushTesting(args) {
-  if (args.has("--no-hook")) return { state: "skipped" };
-  const current = (() => {
-    try {
-      return hookStatus({ probe: true });
-    } catch {
-      return null; // not a git repository
-    }
-  })();
-  if (!current) {
-    process.stdout.write(`${MARK.skip()} Not a git repository — no push testing here.\n`);
-    return { state: "unavailable" };
-  }
-  // A hook whose invocation went stale, or no longer answers, is reinstalled
-  // rather than reported as on: it is the case where PreMan looks connected and
-  // silently checks nothing.
-  if (current.state === "installed" && current.current && current.works) {
-    process.stdout.write(`${MARK.ok()} Push testing already on.\n`);
-    return { state: "installed" };
-  }
-
-  const result = installHook(args);
-  if (result.action === "conflict") {
-    process.stdout.write(
-      `${MARK.skip()} You already have a pre-push hook. Replace it: ${cliInvocation()} hook install --force\n`
-    );
-    return result;
-  }
-  if (result.action === "unproven") {
-    process.stdout.write(
-      `${MARK.skip()} No push testing: ${result.detail}\n` +
-        `   Then: ${cliInvocation()} hook install\n`
-    );
-    return result;
-  }
-  process.stdout.write(
-    `${MARK.ok()} Push testing on — \`git push\` now checks the endpoints you touched.\n` +
-      "   It never blocks a push; PREMAN_SKIP_HOOK=1 silences it.\n"
-  );
-  return result;
-}
-
-/**
- * Everything after the link, in one pass, for whoever asks for it with `--guide`.
- *
- * Order follows what a new account needs to see: what PreMan found, then where to
- * watch it, then who to tell, then when to run it. It is opt-in because running
- * all of it unasked is what turned a finished connect into a screen of prompts,
- * a dead runner and a five-minute wait on an integration nobody had asked for.
- */
-async function guidedFirstRun(args, agent, apiKey, serverName, { blockedHere = "" } = {}) {
-  const assumeYes = args.has("--yes");
-
-  step("Endpoints");
-  const counts = await discoverEndpoints(args, agent, serverName, blockedHere);
-
-  if (counts.first) {
-    step("First test");
-    await runFirstTest(args, counts.first, { assumeYes });
-  }
-
-  step("Runner");
-  await setUpRunner(args, agent, { assumeYes });
-
-  step("Desktop app");
-  await offerDesktop(args, { assumeYes });
-
-  step("Integrations");
-  await connectIntegrations(args, apiKey, { assumeYes });
-
-  step("Testing on push");
-  await setUpPushTesting(args);
-
-  process.stdout.write(`\nDone. Watch it at ${frontendUrl(args)}\n`);
-}
+import { MARK } from "./integrations.js";
+import { ConnectError, EXIT_USAGE } from "./connect/errors.js";
+import {
+  agentBlocker,
+  detectAgents,
+  findAgent,
+  promptAgentChoice,
+} from "./connect/agents.js";
+import {
+  WRITERS,
+  renderAgentSnippet,
+  renderAllAgentSnippets,
+  renderCodexToml,
+  verifyWrittenConfig,
+} from "./connect/configs.js";
+import { checkKeyAndPair, refreshStaleCredentials } from "./connect/pairing.js";
+import {
+  autoCheckIn,
+  lastLine,
+  mcpSelfTest,
+  pollTicker,
+  selfTestBudgetMs,
+  waitForConnection,
+} from "./connect/checkin.js";
+import { captureDispatchCredential } from "./connect/dispatch.js";
+import {
+  discoverEndpoints,
+  guidedFirstRun,
+  nextStepsBlock,
+  setUpPushTesting,
+  whatIsLeftBlock,
+} from "./connect/guide.js";
 
 // ── Preflight ───────────────────────────────────────────────────────────
 
@@ -1683,7 +183,7 @@ export async function connectCommand(commandArgs) {
 
   if (printOnly) {
     if (!agent) agent = await promptAgentChoice(detectAgents());
-    const serverConfig = buildServerConfig(args);
+    const serverConfig = buildServerConfig(args, { codingAgent: agent.id });
     if (agent.id === "codex") {
       process.stdout.write(renderCodexToml(serverName, serverConfig));
     } else {
@@ -1715,6 +215,7 @@ export async function connectCommand(commandArgs) {
   let apiKey = resolveApiKey(args);
 
   let pairCode = "";
+  let pairingId = "";
   if (apiKey) {
     let pairing = await checkKeyAndPair(args, agent, apiKey);
     if (pairing.stale) {
@@ -1725,9 +226,13 @@ export async function connectCommand(commandArgs) {
       }
     }
     pairCode = pairing.pairCode;
+    pairingId = pairing.pairingId;
   }
 
-  const serverConfig = buildServerConfig(args, { pairCode });
+  const serverConfig = buildServerConfig(args, {
+    pairCode,
+    codingAgent: agent.id,
+  });
   const written = WRITERS[agent.id]({ serverName, serverConfig, projectInstall });
 
   process.stdout.write(
@@ -1741,7 +246,7 @@ export async function connectCommand(commandArgs) {
     // Generate hint that matches the actual install location
     let hint = agent.snippetHint;
     if (agent.id === "cursor" && projectInstall) {
-      hint = "merge into .cursor/mcp.json";
+      hint = `merge into .cursor/mcp.json, then run: cursor-agent mcp enable ${serverName}`;
     } else if (agent.id === "claude_code") {
       hint = projectInstall ? "run (with --scope project):" : "run:";
     }
@@ -1766,6 +271,7 @@ export async function connectCommand(commandArgs) {
     written,
     serverConfig,
     projectInstall,
+    pairingId,
   });
   // The agent goes back to the caller because `onboard` runs steps after this one
   // that need to know which agent to drive, and asking twice is a question we
@@ -1793,6 +299,16 @@ export async function connectCommand(commandArgs) {
   }
   if (!args.has("--no-guide")) {
     await setUpPushTesting(args);
+    // Discovery is back inline, alone. What made the old full pass bad was its
+    // tail — a runner that fails on its own and a five-minute GitHub poll, after
+    // the link had already succeeded. Discovery is the one step PreMan is
+    // useless without: with no endpoints there is nothing to test, nothing to
+    // schedule and nothing for the push hook just installed above to check. It
+    // asks nothing, never throws, and skips itself when the repo is already
+    // mapped or no agent can be run.
+    await discoverEndpoints(args, agent, serverName, {
+      blockedHere: checkIn.blockedHere,
+    });
     process.stdout.write(whatIsLeftBlock(args));
   }
   await captureDispatchCredential(args, agent, apiKey, { prompt: false });
@@ -1870,7 +386,7 @@ async function establishCheckIn(
   args,
   agent,
   apiKey,
-  { serverName, written, serverConfig, projectInstall = false }
+  { serverName, written, serverConfig, projectInstall = false, pairingId = "" }
 ) {
   const notes = [];
   // Both set only when this directory redirects the agent: where it can be
@@ -1901,7 +417,15 @@ async function establishCheckIn(
           `so your agent will use ${status.backend_url}.`
       );
     }
-    if (test.ok && status.authenticated && (await waitForConnection(args, apiKey, { timeoutMs: 15000 }))) {
+    if (
+      test.ok &&
+      status.authenticated &&
+      (await waitForConnection(args, apiKey, {
+        timeoutMs: 15000,
+        expectedAgent: agent.id,
+        pairingId,
+      }))
+    ) {
       return done(true);
     }
     note(
@@ -1959,7 +483,11 @@ async function establishCheckIn(
       if (
         retry.ok &&
         retry.status?.authenticated &&
-        (await waitForConnection(args, apiKey, { timeoutMs: 15000 }))
+        (await waitForConnection(args, apiKey, {
+          timeoutMs: 15000,
+          expectedAgent: agent.id,
+          pairingId,
+        }))
       ) {
         return done(true);
       }
@@ -1984,6 +512,7 @@ async function establishCheckIn(
     launch = await autoCheckIn(args, agent, apiKey, {
       serverName,
       cwd: elsewhere || process.cwd(),
+      pairingId,
       onPoll: ticker.tick,
       onLaunch: ({ mode, terminal }) =>
         say(
@@ -2021,7 +550,13 @@ async function establishCheckIn(
           "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
   );
 
-  if (await waitForConnection(args, apiKey, { onPoll: ticker.tick })) {
+  if (
+    await waitForConnection(args, apiKey, {
+      expectedAgent: agent.id,
+      pairingId,
+      onPoll: ticker.tick,
+    })
+  ) {
     ticker.end();
     return done(true);
   }
@@ -2036,3 +571,15 @@ async function establishCheckIn(
   );
   return done(false);
 }
+
+// ── Facade ──────────────────────────────────────────────────────────────
+
+// Kept so every existing importer -- cli.js, the smoke suites, and the two
+// that reach in by dynamic import -- sees the surface it always did.
+
+export { agentBlocker, resolveAgentForPairing, resolveAgentToDrive, runningInside } from "./connect/agents.js";
+export { autoCheckIn, commandLine, headlessCheckIn, interactiveCheckIn, lastLine, mcpSelfTest, openInNewTerminal, selfTestBudgetMs, waitForConnection } from "./connect/checkin.js";
+export { claudeMcpAddArgs, cursorMcpEnableArgs, renderAgentSnippet, renderAllAgentSnippets, renderCodexToml, upsertCodexToml, verifyWrittenConfig, writeClaudeConfig, writeCodexConfig, writeCursorConfig } from "./connect/configs.js";
+export { DISPATCH_HELP, dispatchCommand, extractRoutineId } from "./connect/dispatch.js";
+export { discoverEndpoints, headlessDiscovery, integrationStatus, runnerPairingIsUsable } from "./connect/guide.js";
+export { ConnectError, EXIT_USAGE } from "./connect/errors.js";