premanmcp 0.8.0 → 0.10.0

package/bin/connect.js

@@ -10,18 +10,24 @@
  * never fails the connect.
  */
 
-import { execFileSync, spawnSync } from "node:child_process";
+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 { 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 { readRunnerState, registerRunner, runnerIsAlive, startBackground } from "./runner.js";
 import {
+  apiKeyIsExplicit,
   assertOk,
   authenticateTerminal,
   backendUrl,
   buildServerConfig,
   callBackendJson,
+  clearStoredCredentials,
   cliInvocation,
   frontendUrl,
   hasKeyAvailable,
@@ -53,7 +59,11 @@ const AGENTS = [
     id: "cursor",
     label: "Cursor",
     aliases: ["cursor"],
-    dispatch: { credential: "Cursor API key", needsRoutine: false },
+    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.',
   },
@@ -61,7 +71,13 @@ const AGENTS = [
     id: "claude_code",
     label: "Claude Code",
     aliases: ["claude", "claude-code", "claude_code", "claudecode"],
-    dispatch: { credential: "Claude Code routine token", needsRoutine: true },
+    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.',
   },
@@ -97,17 +113,36 @@ function detectAgents() {
   };
 }
 
-async function promptAgentChoice(detected) {
+/**
+ * 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 "";
+}
+
+async function promptAgentChoice(detected, insideId = runningInside()) {
   process.stdout.write("Which coding agent?\n");
   AGENTS.forEach((agent, index) => {
-    const mark = detected[agent.id] ? "  (detected)" : "";
+    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 defaultIndex = Math.max(
-    0,
-    AGENTS.findIndex((a) => detected[a.id])
-  );
+  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];
 
@@ -360,19 +395,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 String(result.pair_code || "");
+  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(
@@ -381,6 +478,7 @@ export async function waitForConnection(
   {
     intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
     timeoutMs = Number(process.env.PREMAN_CONNECT_WAIT_MS) || 300000,
+    stopWhen = null,
   } = {}
 ) {
   const deadline = Date.now() + timeoutMs;
@@ -396,6 +494,7 @@ export async function waitForConnection(
         token: apiKey,
       });
       if (status.ok && status.connected) return true;
+      if (stopWhen && stopWhen()) return false;
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
   } finally {
@@ -404,9 +503,247 @@ export async function waitForConnection(
   return false;
 }
 
+// ── 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 = `Call the ${serverName} MCP tool preman_status and report the result.`;
+  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;
+}
+
+/**
+ * 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 run the agent
+ * headlessly and poll for the check-in it produces.
+ *
+ * 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,
+  } = {}
+) {
+  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, { 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();
+  });
+  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,
+      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) {
+async function captureDispatchCredential(args, agent, apiKey, { prompt = true } = {}) {
   if (!agent.dispatch) return;
   if (args.has("--skip-dispatch-credential")) return;
 
@@ -414,19 +751,20 @@ async function captureDispatchCredential(args, agent, apiKey) {
   let routineId = args.value("--routine-id", "");
 
   if (!secret) {
-    if (!process.stdin.isTTY) return;
+    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(
-      `\nLet PreMan start ${agent.label} runs for you — it can then apply fixes and\n` +
-        `run checks on a schedule instead of only telling you what to do.\n`
+      `\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 set up later): `);
+    secret = await promptSecret(`Paste your ${agent.dispatch.credential} (Enter to skip): `);
     if (!secret) {
       process.stdout.write(
-        `Skipped. Run '${cliInvocation()} connect --agent ${agent.id.replace("_", "-")}' when you have the token.\n`
+        `Skipped. Run '${cliInvocation()} dispatch --agent ${agent.id.replace("_", "-")}' when you have the token.\n`
       );
       return;
     }
@@ -458,6 +796,64 @@ async function captureDispatchCredential(args, agent, apiKey) {
   }
 }
 
+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();
@@ -476,81 +872,381 @@ 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");
+async function confirm(question, { assumeYes = false, defaultYes = true } = {}) {
+  if (assumeYes) return true;
+  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.
  *
- * Never throws: onboarding help must not turn a successful connect into a failure.
+ * 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.
  */
-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 || []);
+    if (!spec || !onPath(spec.bin)) {
+      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) {
+      const why = outcome.reason || lastLine(outcome.output) || "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,
+      });
+    });
+  });
+}
 
-    const brief = await callPremanTool(args, "discover_endpoints_from_codebase", { base_path: "." });
-    for (const line of brief.instructions || []) process.stdout.write(`${line}\n`);
+/** 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(
-      `\nHand this brief to ${agent.label}, then run:\n` +
-        "  preman endpoints setup --file endpoints.json\n" +
-        "  preman test <request-id>\n"
+      `${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([]);
+    process.stdout.write(
+      `${MARK.ok()} Runner running (pid ${started.pid}) — PreMan can apply fixes on this machine.\n` +
+        `   Log: ${started.log}   Stop: ${cliInvocation()} runner stop\n`
+    );
+    return { state: "running", pid: started.pid };
   } catch (error) {
     process.stdout.write(
-      `Note: ${error.message}. Run \`preman endpoints list\` when you are ready.\n`
+      `${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. */
+async function setUpPushTesting(args, { assumeYes }) {
+  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" };
+  }
+  if (current.state === "installed") {
+    process.stdout.write(`${MARK.ok()} Push testing already on.\n`);
+    return { state: "installed" };
+  }
+  if (!(await confirm("Test the endpoints you touched on every git push?", { assumeYes }))) {
+    process.stdout.write(`${MARK.skip()} Skipped. Turn it on: ${cliInvocation()} hook install\n`);
+    return { state: "skipped" };
+  }
+
+  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;
+  }
+  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, { assumeYes });
+
+  process.stdout.write(`\nDone. Watch it at ${frontendUrl(args)}\n`);
+}
+
 // ── Preflight ───────────────────────────────────────────────────────────
 
 const MIN_NODE_MAJOR = 18;
@@ -602,6 +1298,7 @@ Connect options:
   --project                   Write project-local config instead of the user config
   --api-key <key>             PreMan API key. If omitted, stored credentials are used
   --email <email>             Pre-fill the email prompt when logging in
+  --password [value]          Also set a dashboard password (signup asks for none)
   --backend <url>             PreMan backend URL
   --frontend <url>            PreMan frontend URL
   --name <name>               MCP server name. Defaults to preman
@@ -610,8 +1307,15 @@ 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                       Accept every optional step without prompting
   --print                     Print the config instead of writing it
 `;
 
@@ -630,31 +1334,23 @@ export async function connectCommand(commandArgs) {
     );
   }
 
-  if (!agent) {
-    if (!interactive) {
-      // Nothing to prompt on, so leave behind everything a CI log needs to
-      // finish the setup by hand rather than just the reason it stopped.
-      process.stdout.write(
-        `preman connect needs a terminal to pick an agent. Copy-paste setup instead:\n\n${renderAllAgentSnippets(args, serverName, { projectInstall })}\n` +
-          'Then restart your agent and ask it: "run preman_status".\n' +
-          "Or rerun: preman connect --agent <cursor|claude-code|codex> --api-key pm_live_…\n"
-      );
-      throw new ConnectError(
-        "preman connect needs a terminal. In CI pass --agent <cursor|claude-code|codex> " +
-          "and --api-key pm_live_… (or --print), or use one of the snippets above.",
-        EXIT_USAGE
-      );
-    }
-    agent = await promptAgentChoice(detectAgents());
-  }
-
-  if (!printOnly) {
-    // Verify the machine can run what we are about to write — before any
-    // config edits or logins, so failures leave nothing half-done.
-    await preflight(args);
+  // Nothing to prompt on, so leave behind everything a CI log needs to finish
+  // the setup by hand rather than just the reason it stopped.
+  if (!agent && !interactive) {
+    process.stdout.write(
+      `preman connect needs a terminal to pick an agent. Copy-paste setup instead:\n\n${renderAllAgentSnippets(args, serverName, { projectInstall })}\n` +
+        'Then restart your agent and ask it: "run preman_status".\n' +
+        "Or rerun: preman connect --agent <cursor|claude-code|codex> --api-key pm_live_…\n"
+    );
+    throw new ConnectError(
+      "preman connect needs a terminal. In CI pass --agent <cursor|claude-code|codex> " +
+        "and --api-key pm_live_… (or --print), or use one of the snippets above.",
+      EXIT_USAGE
+    );
   }
 
   if (printOnly) {
+    if (!agent) agent = await promptAgentChoice(detectAgents());
     const serverConfig = buildServerConfig(args);
     if (agent.id === "codex") {
       process.stdout.write(renderCodexToml(serverName, serverConfig));
@@ -664,6 +1360,12 @@ export async function connectCommand(commandArgs) {
     return;
   }
 
+  // Verify the machine can run what we are about to write — before any config
+  // edits or logins, so failures leave nothing half-done.
+  await preflight(args);
+
+  // Account first, so "First, let's connect your PreMan account" is not the
+  // second thing that happens.
   if (!args.has("--skip-login") && !hasKeyAvailable(args)) {
     if (!interactive) {
       throw new ConnectError(
@@ -676,11 +1378,21 @@ export async function connectCommand(commandArgs) {
     process.stdout.write("\n");
   }
 
-  const apiKey = resolveApiKey(args);
+  if (!agent) agent = await promptAgentChoice(detectAgents());
+
+  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 });
@@ -708,32 +1420,105 @@ export async function connectCommand(commandArgs) {
     );
   }
 
-  // Not gated on TTY: --dispatch-credential is the non-interactive path, and the
-  // prompt inside only runs when there is a terminal to prompt on.
-  await captureDispatchCredential(args, agent, apiKey);
-
+  // A non-interactive run can still be handed the credential up front, so this
+  // stays reachable; the prompt inside only fires when there is a TTY, and by
+  // then onboarding is done.
   if (!pairCode || args.has("--no-wait") || !interactive) {
+    await captureDispatchCredential(args, agent, apiKey);
     process.stdout.write(nextStepsBlock(agent));
     return;
   }
 
+  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(`${MARK.ok()} Connected as ${agent.label}.\n`);
+  if (!args.has("--no-guide")) {
+    await guidedFirstRun(args, agent, apiKey, serverName);
+  }
+  await captureDispatchCredential(args, agent, apiKey);
+}
+
+/**
+ * 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.
+ *
+ * Returns whether the check-in landed, and prints the troubleshooting block
+ * itself when it did not.
+ */
+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}` : ""})`
+    );
+  }
+
+  if (!args.has("--no-auto-checkin")) {
+    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) {
+      for (const note of notes) process.stdout.write(`Note: ${note}\n`);
+      return true;
+    }
+    if (auto.ran) {
+      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`);
+    }
+  }
+
   process.stdout.write(
     `\nRestart ${agent.label} and ask it: "run preman_status"\n` +
       "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
   );
 
-  if (!(await waitForConnection(args, apiKey))) {
-    process.stdout.write(
-      "No check-in yet. Troubleshooting:\n" +
-        `  - ${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`
-    );
-    return;
+  if (await waitForConnection(args, apiKey)) {
+    for (const note of notes) process.stdout.write(`Note: ${note}\n`);
+    return true;
   }
 
-  process.stdout.write(`Connected as ${agent.label}.\n`);
-  if (!args.has("--no-guide")) {
-    await guidedFirstRun(args, agent);
-  }
+  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` +
+      `  - Then: ${cliInvocation()} connect --agent ${agent.id.replace("_", "-")}\n`
+  );
+  return false;
 }