premanmcp 0.9.0 → 0.10.1

package/bin/connect.js

@@ -16,18 +16,31 @@ import os from "node:os";
 import path from "node:path";
 
 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,
+  readRunnerState,
+  registerRunner,
+  runnerIsAlive,
+  startBackground,
+} from "./runner.js";
+import {
+  apiKeyIsExplicit,
   assertOk,
   authenticateTerminal,
   backendUrl,
   buildServerConfig,
   callBackendJson,
+  clearStoredCredentials,
   cliInvocation,
   frontendUrl,
   hasKeyAvailable,
   LAUNCHER_ARGS,
   LAUNCHER_COMMAND,
   makeArgs,
+  pathPremanOwner,
   promptSecret,
   promptText,
   readJsonFile,
@@ -97,6 +110,29 @@ function onPath(binary) {
   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();
@@ -389,19 +425,81 @@ export function verifyWrittenConfig(agent, { serverName, written }) {
 
 // ── 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 "";
+    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
+    );
   }
-  return String(result.pair_code || "");
+  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(
@@ -487,13 +585,24 @@ export async function autoCheckIn(
 
   let child;
   try {
-    child = spawn(spec.bin, spec.args, { stdio: "ignore" });
+    // 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, { stdio: ["ignore", "pipe", "pipe"] });
   } catch (error) {
     return { ran: false, connected: false, reason: error.message };
   }
 
   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();
@@ -512,14 +621,156 @@ export async function autoCheckIn(
       stopWhen: () => Boolean(exitedAt) && Date.now() - exitedAt > grace,
     });
     if (spawnError && !connected) {
-      return { ran: false, connected: false, reason: spawnError.message };
+      return { ran: false, connected: false, reason: spawnError.message, output };
     }
-    return { ran: true, connected, command: spec.bin };
+    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 } = {}) {
@@ -651,79 +902,418 @@ function nextStepsBlock(agent) {
   return (
     "\nNext steps:\n" +
     `  1. Restart ${agent.label}, then ask it: "run preman_status" to finish linking.\n` +
-    "  2. preman endpoints discover                     # brief for your agent → endpoints.json\n" +
-    "  3. preman endpoints setup --file endpoints.json  # register runnable requests\n" +
-    "  4. preman test <request-id>                      # generate + run your first scenarios\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`
   );
 }
 
-async function confirm(question) {
-  const answer = (await promptText(`${question} [Y/n]: `)).toLowerCase();
-  return answer === "" || answer.startsWith("y");
+/**
+ * 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,
+  };
 }
 
 /**
- * Carry a freshly linked agent to its first passing test.
+ * The one-shot command that has an agent execute the discovery brief.
  *
- * Discovery itself belongs to the coding agent — the backend hands back a brief
- * for it to execute — so this either runs a test against what the account
- * already has, or prints that brief and the two commands that follow it.
+ * 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: onboarding help must not turn a successful connect into a failure.
+ * Never throws: a failed discovery must not fail the connect.
  */
-async function guidedFirstRun(args, agent) {
+async function discoverEndpoints(args, agent, serverName) {
   try {
-    const inventory = await callPremanTool(args, "get_endpoints", {
-      include_workbench: true,
-      limit: 50,
-    });
-    const runnable = (inventory.workbench_requests || [])[0];
-    const registered = (inventory.endpoints || []).length;
-
-    if (runnable) {
-      const label = `${runnable.method || "GET"} ${runnable.url || ""}`.trim();
-      if (!(await confirm(`\nRun a first test against ${label}?`))) {
-        process.stdout.write(`Whenever you are ready: preman test ${runnable.id}\n`);
-        return;
-      }
-      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);
-      process.stdout.write(`\nAdd your own: preman test ${runnable.id} --scenario "..."\n`);
-      return;
+    const before = await endpointCounts(args);
+    if (before.registered) {
+      process.stdout.write(
+        `${MARK.ok()} ${before.registered} endpoint(s) · ${before.runnable} runnable\n`
+      );
+      return before;
     }
 
-    if (registered) {
+    const brief = await callPremanTool(args, "discover_endpoints_from_codebase", { base_path: "." });
+    const spec = headlessDiscovery(agent, serverName, brief.instructions || []);
+    const blocker = 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(
-        `\nYou have ${registered} registered endpoint(s), but none are runnable yet:\n` +
-          "  preman endpoints setup --ids <id1,id2>    # make them runnable\n" +
-          "  preman test <request-id>                  # generate + run your first scenarios\n"
+        `${MARK.fail()} ${agent.label} did not register any endpoints (${why}).\n` +
+          `   Run it yourself: ${cliInvocation()} endpoints discover\n`
       );
-      return;
+      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 };
+  }
+}
 
-    if (!(await confirm("\nNo endpoints in PreMan yet. Print the discovery brief for your agent?"))) {
-      process.stdout.write(`\nWhen you are ready:\n${MANUAL_STEPS}`);
+/** 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`);
+  }
+}
+
+/**
+ * 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 (!existing || existing.agent !== agent.id || existing.project_path !== path.resolve(process.cwd())) {
+      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 };
+  }
+}
 
-    const brief = await callPremanTool(args, "discover_endpoints_from_codebase", { base_path: "." });
-    for (const line of brief.instructions || []) process.stdout.write(`${line}\n`);
+/** 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(
-      `\nHand this brief to ${agent.label}, then run:\n` +
-        "  preman endpoints setup --file endpoints.json\n" +
-        "  preman test <request-id>\n"
+      `${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();
+    } 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 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) {
+    process.stdout.write(`${MARK.ok()} Push testing already on.\n`);
+    return { state: "installed" };
+  }
+
+  const result = installHook(args);
+  if (result.action === "conflict") {
     process.stdout.write(
-      `Note: ${error.message}. Run \`preman endpoints list\` when you are ready.\n`
+      `${MARK.skip()} You already have a pre-push hook. Replace it: ${cliInvocation()} hook install --force\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, with nothing left for the user to run.
+ *
+ * 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.
+ */
+async function guidedFirstRun(args, agent, apiKey, serverName) {
+  const assumeYes = args.has("--yes");
+
+  step("Endpoints");
+  const counts = await discoverEndpoints(args, agent, serverName);
+
+  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`);
 }
 
 // ── Preflight ───────────────────────────────────────────────────────────
@@ -752,6 +1342,16 @@ export async function preflight(args) {
     );
   }
 
+  // Explains why every command below is spelled the long way, before someone
+  // types `preman …` and gets another package's CLI answering.
+  const premanOwner = pathPremanOwner();
+  if (premanOwner && premanOwner !== "premanmcp") {
+    notes.push(
+      `\`preman\` on your PATH belongs to ${premanOwner}, not this CLI, so PreMan's own ` +
+        "commands are written out as `npm exec -y premanmcp@latest -- …`."
+    );
+  }
+
   try {
     const resp = await fetch(new URL("health", `${backendUrl(args)}/`), {
       signal: AbortSignal.timeout(4000),
@@ -786,9 +1386,16 @@ Connect options:
   --skip-dispatch-credential  Do not ask for a cloud-dispatch credential
   --skip-login                Write config without interactive terminal auth
   --no-pair                   Do not mint a pair code
+  --no-self-test              Do not start the MCP server to finish the link
   --no-auto-checkin           Do not run the agent to finish the link
   --no-wait                   Do not wait for the agent to check in
   --no-guide                  Skip the guided first run after connecting
+  --no-runner                 Do not pair this machine as a job runner
+  --no-desktop                Do not offer the desktop app
+  --no-integrations           Do not check or offer GitHub / AWS / Slack
+  --no-hook                   Do not install the git pre-push hook
+  --yes                       Take every step's default without prompting
+                              (the desktop app defaults to no; install-desktop)
   --print                     Print the config instead of writing it
 `;
 
@@ -853,11 +1460,19 @@ export async function connectCommand(commandArgs) {
 
   if (!agent) agent = await promptAgentChoice(detectAgents());
 
-  const apiKey = resolveApiKey(args);
+  let apiKey = resolveApiKey(args);
 
   let pairCode = "";
-  if (apiKey && !args.has("--no-pair")) {
-    pairCode = await startPairing(args, agent, apiKey);
+  if (apiKey) {
+    let pairing = await checkKeyAndPair(args, agent, apiKey);
+    if (pairing.stale) {
+      apiKey = await refreshStaleCredentials(args);
+      pairing = await checkKeyAndPair(args, agent, apiKey);
+      if (pairing.stale) {
+        throw new ConnectError("PreMan rejected a key it just issued. Try again shortly.");
+      }
+    }
+    pairCode = pairing.pairCode;
   }
 
   const serverConfig = buildServerConfig(args, { pairCode });
@@ -894,38 +1509,83 @@ export async function connectCommand(commandArgs) {
     return;
   }
 
-  if (!(await establishCheckIn(args, agent, apiKey, { serverName, written }))) {
+  if (!(await establishCheckIn(args, agent, apiKey, { serverName, written, serverConfig }))) {
     // Still honour an explicitly-passed credential, but do not open a new prompt
     // on top of a connect that just told the user something went wrong.
     await captureDispatchCredential(args, agent, apiKey, { prompt: false });
     return;
   }
 
-  process.stdout.write(`Connected as ${agent.label}.\n`);
+  process.stdout.write(`${MARK.ok()} Connected as ${agent.label}.\n`);
   if (!args.has("--no-guide")) {
-    await guidedFirstRun(args, agent);
+    await guidedFirstRun(args, agent, apiKey, serverName);
   }
   await captureDispatchCredential(args, agent, apiKey);
 }
 
 /**
- * Get the agent to make its first PreMan call, by whatever means work here.
+ * Finish the link here, by whatever means work, in cheapest-first order.
+ *
+ * 1. Run the MCP server ourselves and call one tool. No agent, no tokens, a few
+ *    seconds, and it proves the launcher/key/backend chain the agent will use.
+ * 2. Failing that, run the agent headlessly — which also proves the agent can
+ *    load the config we wrote.
+ * 3. Failing that, ask them to restart it and wait, which is all this ever did.
  *
- * Prefers running it for the user; falls back to asking them to restart it and
- * waiting, which is all this ever did. Returns whether the check-in landed, and
- * prints the troubleshooting block itself when it did not.
+ * Returns whether the check-in landed, and prints the troubleshooting block
+ * itself when it did not.
  */
-async function establishCheckIn(args, agent, apiKey, { serverName, written }) {
-  if (!args.has("--no-auto-checkin")) {
+async function establishCheckIn(args, agent, apiKey, { serverName, written, serverConfig }) {
+  const notes = [];
+
+  if (!args.has("--no-self-test") && serverConfig && selfTestBudgetMs() > 0) {
+    process.stdout.write("\nChecking the connection…\n");
+    const test = await mcpSelfTest(serverConfig);
+    const status = test.status || {};
+    const repo = status.config?.repo_config;
+    if (repo?.override && repo.applied?.length) {
+      // The one failure that reads as a bad key: a working server talking to a
+      // backend nobody chose. Name the file before it costs anyone an hour.
+      notes.push(
+        `${repo.path} overrides ${repo.applied.join(", ")} for anything started in this directory, ` +
+          `so your agent will use ${status.backend_url}.`
+      );
+    }
+    if (test.ok && status.authenticated && (await waitForConnection(args, apiKey, { timeoutMs: 15000 }))) {
+      for (const note of notes) process.stdout.write(`Note: ${note}\n`);
+      return true;
+    }
+    notes.push(
+      test.ok
+        ? `the MCP server answered from ${status.backend_url || "an unknown backend"} but was not authenticated`
+        : `the MCP server could not be started (${test.reason || "unknown"}${test.stderr ? `: ${test.stderr}` : ""})`
+    );
+  }
+
+  const blocker = agentBlocker(agent.id);
+  if (!args.has("--no-auto-checkin") && !blocker) {
     const spec = headlessCheckIn(agent, serverName);
     if (spec && onPath(spec.bin)) {
       process.stdout.write(`\nStarting ${agent.label} to finish the link…\n`);
     }
     const auto = await autoCheckIn(args, agent, apiKey, { serverName });
-    if (auto.connected) return true;
+    if (auto.connected) {
+      for (const note of notes) process.stdout.write(`Note: ${note}\n`);
+      return true;
+    }
     if (auto.ran) {
-      process.stdout.write(`${agent.label} ran but did not check in.\n`);
+      const why = lastLine(auto.output);
+      process.stdout.write(
+        `${agent.label} ran but did not check in${why ? `: ${why}` : "."}\n`
+      );
+    } else if (auto.reason) {
+      process.stdout.write(`Could not run ${agent.label}: ${auto.reason}\n`);
     }
+  } else if (blocker) {
+    // Starting an agent that cannot authenticate spends two minutes to learn
+    // what one status probe already knows.
+    process.stdout.write(`${MARK.skip()} ${blocker}\n`);
+    notes.push(blocker);
   }
 
   process.stdout.write(
@@ -933,10 +1593,14 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written }) {
       "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
   );
 
-  if (await waitForConnection(args, apiKey)) return true;
+  if (await waitForConnection(args, apiKey)) {
+    for (const note of notes) process.stdout.write(`Note: ${note}\n`);
+    return true;
+  }
 
   process.stdout.write(
     "No check-in yet. Troubleshooting:\n" +
+      notes.map((note) => `  - ${note}\n`).join("") +
       `  - ${agent.restartHint}\n` +
       `  - Config written to: ${written.path}\n` +
       `  - Then ask ${agent.label} to "run preman_status" — it links on its first PreMan call.\n` +