premanmcp 0.10.0 → 0.10.2

package/README.md

@@ -48,13 +48,19 @@ to go restart anything, in cheapest-first order:
 1. **Self-test.** It starts the MCP server exactly as your agent will and calls
    `preman_status` over stdio. That both completes the link and proves the whole chain —
    launcher, package, key, backend. `--no-self-test` turns it off.
-2. **Headless agent run** (`claude -p`, `cursor-agent -p`, `codex exec`), which also
-   proves your agent can load what was written. `--no-auto-checkin` turns it off.
+2. **Agent run**, which also proves your agent can load what was written. It opens your
+   agent interactively in a new terminal window — the session you go on to use — and falls
+   back to a headless run (`claude -p`, `cursor-agent -p`, `codex exec`) where no window can
+   be opened, such as CI or SSH. `--no-auto-checkin` turns it off, `PREMAN_NO_TERMINAL=1`
+   keeps it headless.
 3. **Wait**, if neither is possible: restart your agent and it links on its first call.
 
 A self-test that answers from an unexpected backend is reported with the file that
 redirected it — a repo-local `preman-mcp.config.json` with `"PREMAN_CONFIG_OVERRIDE": true`
-wins over the MCP config env, and otherwise only fills in what the env leaves unset.
+wins over the MCP config env, and otherwise only fills in what the env leaves unset. When
+that file overrides `PREMAN_BACKEND`, `connect` stops there rather than waiting: an agent
+started in that directory reads the same file and checks in somewhere else, so it names the
+file and tells you how to connect to either backend.
 
 Once linked, `connect` finishes onboarding without handing you homework:
 
@@ -68,9 +74,13 @@ Once linked, `connect` finishes onboarding without handing you homework:
 | Testing on push | Installs the git pre-push hook, so `git push` checks the endpoints you touched |
 
 Useful flags: `--agent cursor|claude-code|codex` skips the picker, `--project` writes
-project-local config, `--print` shows the config without writing it, `--yes` accepts every
-optional step, `--no-guide` skips all of them, and `--no-runner` / `--no-desktop` /
-`--no-integrations` / `--no-hook` skip one each.
+project-local config, `--print` shows the config without writing it, `--yes` takes every
+step's default without asking, `--no-guide` skips all of them, and `--no-runner` /
+`--no-desktop` / `--no-integrations` / `--no-hook` skip one each.
+
+`--yes` deliberately does *not* install the desktop app: that step's default is no, because
+it downloads a hundred-odd megabytes and writes to `/Applications`. Run `install-desktop`
+when you want it.
 
 In CI or any non-interactive shell, run `connect --agent <name> --api-key pm_live_…`.
 Without `--agent` there is nothing to prompt on, so `connect` prints ready-to-paste

package/bin/account.js

@@ -178,7 +178,7 @@ export async function watchCommand(commandArgs = []) {
   const integrationId = args.value("--integration", positional[1] || "");
   if (!runId || !integrationId) {
     throw new Error(
-      "usage: watch <run-id> <integration-id>  (both are shown by `preman status`)"
+      `usage: watch <run-id> <integration-id>  (both are shown by \`${cliInvocation()} status\`)`
     );
   }
 

package/bin/api_tools.js

@@ -45,7 +45,7 @@ export async function callTool(args, tool, toolArguments) {
   const token = resolveApiKey(args);
   if (!token) {
     throw new CliError(
-      "No PreMan API key. Run `preman login` or pass --api-key pm_live_...",
+      `No PreMan API key. Run \`${cliInvocation()} login\` or pass --api-key pm_live_...`,
       2,
     );
   }
@@ -110,7 +110,7 @@ export async function endpointsCommand(commandArgs) {
     if (args.has("--json-out")) return printJson(result);
     for (const line of result.instructions || []) process.stdout.write(`${line}\n`);
     process.stdout.write(
-      "\nHand this brief to your coding agent, then run `preman endpoints setup --file endpoints.json`.\n",
+      `\nHand this brief to your coding agent, then run \`${cliInvocation()} endpoints setup --file endpoints.json\`.\n`,
     );
     return undefined;
   }

package/bin/connect.js

@@ -19,7 +19,13 @@ 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 {
+  confirmRunnerOnline,
+  readRunnerState,
+  registerRunner,
+  runnerIsAlive,
+  startBackground,
+} from "./runner.js";
 import {
   apiKeyIsExplicit,
   assertOk,
@@ -34,6 +40,7 @@ import {
   LAUNCHER_ARGS,
   LAUNCHER_COMMAND,
   makeArgs,
+  pathPremanOwner,
   promptSecret,
   promptText,
   readJsonFile,
@@ -103,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();
@@ -479,6 +509,9 @@ export async function waitForConnection(
     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;
@@ -495,6 +528,7 @@ export async function waitForConnection(
       });
       if (status.ok && status.connected) return true;
       if (stopWhen && stopWhen()) return false;
+      if (onPoll) onPoll();
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
   } finally {
@@ -503,6 +537,22 @@ export async function waitForConnection(
   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 ───────────────────────────────────────────────────────
 
 /**
@@ -514,7 +564,7 @@ export async function waitForConnection(
  * prompting.
  */
 export function headlessCheckIn(agent, serverName) {
-  const prompt = `Call the ${serverName} MCP tool preman_status and report the result.`;
+  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}`] };
@@ -523,13 +573,122 @@ export function headlessCheckIn(agent, serverName) {
   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 run the agent
- * headlessly and poll for the check-in it produces.
+ * 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.
  *
  * Returns `ran: false` when the agent's binary is absent or will not start, and
  * the caller falls back to the printed instructions.
@@ -547,8 +706,23 @@ export async function autoCheckIn(
     ),
     serverName = "preman",
     intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
+    onLaunch = () => {},
+    onPoll = null,
   } = {}
 ) {
+  const session = interactiveCheckIn(agent, serverName);
+  if (session && onPath(session.bin)) {
+    const { opened, terminal } = openInNewTerminal(commandLine(session), { cwd: process.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` };
@@ -562,6 +736,7 @@ export async function autoCheckIn(
   } catch (error) {
     return { ran: false, connected: false, reason: error.message };
   }
+  onLaunch({ mode: "headless", bin: spec.bin });
 
   let spawnError = null;
   let exitedAt = 0;
@@ -588,6 +763,7 @@ export async function autoCheckIn(
     const connected = await waitForConnection(args, apiKey, {
       intervalMs,
       timeoutMs,
+      onPoll,
       stopWhen: () => Boolean(exitedAt) && Date.now() - exitedAt > grace,
     });
     if (spawnError && !connected) {
@@ -878,8 +1054,17 @@ function nextStepsBlock(agent) {
   );
 }
 
+/**
+ * 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 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;
@@ -951,7 +1136,11 @@ async function discoverEndpoints(args, agent, serverName) {
 
     const brief = await callPremanTool(args, "discover_endpoints_from_codebase", { base_path: "." });
     const spec = headlessDiscovery(agent, serverName, brief.instructions || []);
-    if (!spec || !onPath(spec.bin)) {
+    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;
@@ -963,7 +1152,11 @@ async function discoverEndpoints(args, agent, serverName) {
     const after = await endpointCounts(args);
 
     if (!after.registered) {
-      const why = outcome.reason || lastLine(outcome.output) || "it registered nothing";
+      // 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`
@@ -1069,10 +1262,28 @@ async function setUpRunner(args, agent, { assumeYes }) {
       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 running (pid ${started.pid}) — PreMan can apply fixes on this machine.\n` +
+      `${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(
@@ -1178,8 +1389,14 @@ async function connectIntegrations(args, apiKey, { assumeYes }) {
   }
 }
 
-/** Install the pre-push hook, so a push is what triggers the tests. */
-async function setUpPushTesting(args, { assumeYes }) {
+/**
+ * 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 {
@@ -1192,14 +1409,12 @@ async function setUpPushTesting(args, { assumeYes }) {
     process.stdout.write(`${MARK.skip()} Not a git repository — no push testing here.\n`);
     return { state: "unavailable" };
   }
-  if (current.state === "installed") {
+  // 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" };
   }
-  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") {
@@ -1242,7 +1457,7 @@ async function guidedFirstRun(args, agent, apiKey, serverName) {
   await connectIntegrations(args, apiKey, { assumeYes });
 
   step("Testing on push");
-  await setUpPushTesting(args, { assumeYes });
+  await setUpPushTesting(args);
 
   process.stdout.write(`\nDone. Watch it at ${frontendUrl(args)}\n`);
 }
@@ -1273,6 +1488,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),
@@ -1315,7 +1540,8 @@ Connect options:
   --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
+  --yes                       Take every step's default without prompting
+                              (the desktop app defaults to no; install-desktop)
   --print                     Print the config instead of writing it
 `;
 
@@ -1443,20 +1669,52 @@ export async function connectCommand(commandArgs) {
   await captureDispatchCredential(args, agent, apiKey);
 }
 
+/**
+ * A repo config that sends every agent started here to a backend the key we just
+ * wrote was not issued for, or null.
+ *
+ * Only an override can do this: without the flag the MCP config's env wins, and
+ * a self-test that disagrees with it is a transient, not a redirect. It matters
+ * because it is the one failure waiting cannot fix — the agent starts in the
+ * same directory, reads the same file, and checks in somewhere else forever.
+ */
+function backendRedirect(repo, status, serverConfig) {
+  if (!repo?.override || !(repo.applied || []).includes("PREMAN_BACKEND")) return null;
+  const trim = (url) => String(url || "").replace(/\/+$/, "");
+  const actual = trim(status.backend_url);
+  const wanted = trim(serverConfig?.env?.PREMAN_BACKEND);
+  if (!actual || !wanted || actual === wanted) return null;
+  return { path: repo.path, actual, wanted };
+}
+
 /**
  * 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.
+ * 2. Failing that, start the agent — in its own window when there is a desktop
+ *    to open one on, headlessly otherwise — 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.
  *
+ * Every diagnosis is printed the moment it is known rather than saved for the
+ * end: the steps below are measured in minutes, and a note that explains what is
+ * happening is worth nothing after it has stopped happening.
+ *
  * 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 = [];
+  const ticker = pollTicker();
+  const say = (text) => {
+    ticker.end();
+    process.stdout.write(text);
+  };
+  const note = (text) => {
+    notes.push(text);
+    say(`Note: ${text}\n`);
+  };
 
   if (!args.has("--no-self-test") && serverConfig && selfTestBudgetMs() > 0) {
     process.stdout.write("\nChecking the connection…\n");
@@ -1466,55 +1724,81 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written, serv
     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(
+      note(
         `${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(
+    note(
       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 redirect = backendRedirect(repo, status, serverConfig);
+    if (redirect) {
+      const flag = `--agent ${agent.id.replace("_", "-")}`;
+      say(
+        `\nNot linked: ${redirect.path} forces PREMAN_BACKEND=${redirect.actual} for anything\n` +
+          `started in this directory, so ${agent.label} cannot check in against ${redirect.wanted}.\n` +
+          `  - Run '${cliInvocation()} connect' from your own project instead of this directory.\n` +
+          `  - Or connect to that backend: ${cliInvocation()} connect ${flag} --backend ${redirect.actual}\n` +
+          `    (needs a key issued by it, and that API running).\n` +
+          `  - Config written to: ${written.path}\n`
+      );
+      return false;
     }
-    const auto = await autoCheckIn(args, agent, apiKey, { serverName });
-    if (auto.connected) {
-      for (const note of notes) process.stdout.write(`Note: ${note}\n`);
+  }
+
+  const blocker = agentBlocker(agent.id);
+  let launch = {};
+  if (!args.has("--no-auto-checkin") && !blocker) {
+    launch = await autoCheckIn(args, agent, apiKey, {
+      serverName,
+      onPoll: ticker.tick,
+      onLaunch: ({ mode, terminal }) =>
+        say(
+          mode === "interactive"
+            ? `\nOpened a new ${terminal} window running ${agent.label}.\n`
+            : `\nStarting ${agent.label} to finish the link…\n`
+        ),
+    });
+    if (launch.connected) {
+      ticker.end();
       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`);
+    if (launch.ran && !launch.interactive) {
+      const why = lastLine(launch.output);
+      say(`${agent.label} ran but did not check in${why ? `: ${why}` : "."}\n`);
+    } else if (!launch.ran && launch.reason) {
+      say(`Could not run ${agent.label}: ${launch.reason}\n`);
     }
+  } else if (blocker) {
+    // Starting an agent that cannot authenticate spends two minutes to learn
+    // what one status probe already knows.
+    say(`${MARK.skip()} ${blocker}\n`);
+    notes.push(blocker);
   }
 
-  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"
+  say(
+    launch.interactive
+      ? `\nAnswer it in the ${agent.label} window — it links on its first PreMan call.\n` +
+          "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
+      : `\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)) {
-    for (const note of notes) process.stdout.write(`Note: ${note}\n`);
+  if (await waitForConnection(args, apiKey, { onPoll: ticker.tick })) {
+    ticker.end();
     return true;
   }
 
-  process.stdout.write(
+  say(
     "No check-in yet. Troubleshooting:\n" +
-      notes.map((note) => `  - ${note}\n`).join("") +
+      notes.map((entry) => `  - ${entry}\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` +

package/bin/hook.js

@@ -56,8 +56,10 @@ if [ -z "\${PREMAN_SKIP_HOOK}" ]; then
   if [ "$preman_status" -eq ${BLOCK_EXIT_CODE} ]; then
     exit ${BLOCK_EXIT_CODE}
   fi
-  if [ "$preman_status" -ne 0 ]; then
-    printf '[preman] checks skipped (%s)\\n' "advisory" >&2
+  if [ "$preman_status" -eq 127 ]; then
+    printf '[preman] the PreMan CLI is not on PATH; push checks skipped\\n' >&2
+  elif [ "$preman_status" -ne 0 ]; then
+    printf '[preman] checks skipped (advisory, exit %s)\\n' "$preman_status" >&2
   fi
 fi
 ${END_MARKER}
@@ -116,11 +118,21 @@ export function uninstallHook() {
   return { path: target, action: "removed" };
 }
 
+/**
+ * `current` is what tells a caller an installed hook still needs rewriting.
+ *
+ * A hook is generated shell holding one invocation, and that invocation can go
+ * stale — the machine gained a `preman` that is not ours, or lost the one that
+ * was. "Installed" then means a file exists that calls the wrong thing on every
+ * push, so anything that skips work when the hook is present has to be able to
+ * tell the difference.
+ */
 export function hookStatus() {
   const target = hookPath();
-  if (!existsSync(target)) return { path: target, state: "absent" };
+  if (!existsSync(target)) return { path: target, state: "absent", current: false };
   const existing = readFileSync(target, "utf8");
-  return { path: target, state: isOurHook(existing) ? "installed" : "foreign" };
+  if (!isOurHook(existing)) return { path: target, state: "foreign", current: false };
+  return { path: target, state: "installed", current: existing === hookBody() };
 }
 
 export async function hookCommand(commandArgs = []) {

package/bin/integrations.js

@@ -17,6 +17,7 @@
 import {
   assertOk,
   callBackendJson,
+  cliInvocation,
   frontendUrl,
   openUrl,
   promptText,
@@ -74,8 +75,10 @@ export class Unrecoverable extends Error {}
  * Returns the truthy value from ``check``, or null on timeout. Ordinary
  * exceptions are swallowed and retried; :class:`Unrecoverable` stops the wait.
  */
-async function waitFor(label, check) {
-  const deadline = Date.now() + POLL_TIMEOUT_MS;
+async function waitFor(label, check, { hint = "", hintAfterMs = 60000 } = {}) {
+  const startedAt = Date.now();
+  const deadline = startedAt + POLL_TIMEOUT_MS;
+  let hinted = false;
   process.stdout.write(`Waiting for ${label}`);
   while (Date.now() < deadline) {
     try {
@@ -91,6 +94,12 @@ async function waitFor(label, check) {
       }
       /* keep waiting; the customer is elsewhere */
     }
+    // A minute of dots is indistinguishable from a hang, and the reason this
+    // waits forever is usually something the customer can act on.
+    if (hint && !hinted && Date.now() - startedAt > hintAfterMs) {
+      hinted = true;
+      process.stdout.write(`\n${hint}\nStill waiting`);
+    }
     process.stdout.write(".");
     await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
   }
@@ -101,7 +110,7 @@ async function waitFor(label, check) {
 function requireKey(args) {
   const apiKey = resolveApiKey(args);
   if (!apiKey) {
-    throw new Error("Not signed in. Run 'preman login' first.");
+    throw new Error(`Not signed in. Run '${cliInvocation()} login' first.`);
   }
   return apiKey;
 }
@@ -156,7 +165,7 @@ export async function awsCommand(args) {
   }
 
   if (!verified) {
-    process.stdout.write("Timed out. Re-run 'preman aws' once the stack finishes.\n");
+    process.stdout.write(`Timed out. Re-run '${cliInvocation()} aws' once the stack finishes.\n`);
     return;
   }
   connected(`AWS connected: ${verified.role_arn}`);
@@ -223,23 +232,35 @@ export async function githubCommand(args) {
   present(url, "install the PreMan GitHub App");
   process.stdout.write("Pick the repositories PreMan may read.\n");
 
-  const done = await waitFor("the installation", async () => {
-    // Installing the App and having repositories appear are two events: the
-    // callback records the installation, and a refresh materialises the repos.
-    // Polling the repo list alone waits for something that may never arrive on
-    // its own.
-    await callBackendJson(args, "POST", "/integrations/github/app/refresh", {
-      token,
-      json: {},
-    });
-    // Compare against what existed before, so a user who already had repos
-    // connected is not told they are done the moment polling starts.
-    const fresh = (await listRepos()).filter((r) => !seen.has(r.id));
-    return fresh.length ? fresh : null;
-  });
+  const done = await waitFor(
+    "the installation",
+    async () => {
+      // Installing the App and having repositories appear are two events: the
+      // callback records the installation, and a refresh materialises the repos.
+      // Polling the repo list alone waits for something that may never arrive on
+      // its own.
+      await callBackendJson(args, "POST", "/integrations/github/app/refresh", {
+        token,
+        json: {},
+      });
+      // Compare against what existed before, so a user who already had repos
+      // connected is not told they are done the moment polling starts.
+      const fresh = (await listRepos()).filter((r) => !seen.has(r.id));
+      return fresh.length ? fresh : null;
+    },
+    {
+      hint:
+        "PreMan has not heard from GitHub yet. Finish the install in the browser tab —\n" +
+        "pick at least one repository and confirm — and GitHub will send you back here.",
+    }
+  );
 
   if (!done) {
-    process.stdout.write("Timed out. Re-run 'preman github' if the install finished.\n");
+    process.stdout.write(
+      `Timed out: GitHub never told PreMan about an installation.\n` +
+        `  - Check that the App is installed: https://github.com/settings/installations\n` +
+        `  - Then re-run '${cliInvocation()} github'.\n`
+    );
     return;
   }
   connected(`GitHub connected: ${done.length} repository(ies).`);
@@ -270,7 +291,7 @@ export async function slackCommand(args) {
   });
 
   if (!done) {
-    process.stdout.write("Timed out. Re-run 'preman slack' if the install finished.\n");
+    process.stdout.write(`Timed out. Re-run '${cliInvocation()} slack' if the install finished.\n`);
     return;
   }
   connected(`Slack connected: ${done[0].team_name || done[0].id}`);

package/bin/runner.js

@@ -24,7 +24,16 @@
 
 import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -603,6 +612,32 @@ function defaultLog(message) {
   process.stdout.write(`[preman runner] ${new Date().toISOString()} ${message}\n`);
 }
 
+/**
+ * One heartbeat. Never throws.
+ *
+ * It runs on a timer, and a rejected fetch inside a timer callback has nobody to
+ * catch it — Node turns that unhandled rejection into process exit, so a single
+ * connect timeout to the backend used to take the whole daemon down mid-run and
+ * leave a machine that reads as paired and never runs anything again. A missed
+ * heartbeat only costs one TTL window: the next one puts this runner back online.
+ */
+export async function sendHeartbeat(args, state, { busy = false, log = () => {} } = {}) {
+  try {
+    // Reported honestly because the matcher prefers idle runners: a busy device
+    // claiming to be idle wins work it will only sit on until the lease expires.
+    const result = await callBackendJson(
+      args,
+      "POST",
+      "/workbench/coding-agent/local-runner/heartbeat",
+      { token: state.runner_token, json: { state: busy ? "busy" : "idle" } }
+    );
+    return { revoked: result.status_code === 401 };
+  } catch (error) {
+    log(`heartbeat failed: ${error.message}`);
+    return { revoked: false };
+  }
+}
+
 /**
  * Hold the stream and run what it leases, until stopped.
  *
@@ -624,17 +659,12 @@ export async function runnerLoop(
     `${state.backend_url || backendUrl(args)}/`
   );
 
-  const heartbeat = setInterval(async () => {
-    // Reported honestly because the matcher prefers idle runners: a busy device
-    // claiming to be idle wins work it will only sit on until the lease expires.
-    const result = await callBackendJson(args, "POST", "/workbench/coding-agent/local-runner/heartbeat", {
-      token: state.runner_token,
-      json: { state: busy ? "busy" : "idle" },
-    });
-    if (result.status_code === 401) {
+  const heartbeat = setInterval(() => {
+    void sendHeartbeat(args, state, { busy, log }).then(({ revoked }) => {
+      if (!revoked) return;
       log("runner registration is no longer active; stopping");
       stopped = true;
-    }
+    });
   }, HEARTBEAT_MS);
 
   try {
@@ -739,9 +769,56 @@ Runner options:
   --full-access                 Let the agent run commands, not just edit files
 `;
 
+function logSize() {
+  try {
+    return statSync(RUNNER_LOG_FILE).size;
+  } catch {
+    return 0;
+  }
+}
+
+/** Whatever the daemon has logged since `offset`, exactly (the log is appended to). */
+export function runnerLogSince(offset = 0) {
+  try {
+    const buffer = readFileSync(RUNNER_LOG_FILE);
+    return buffer.subarray(Math.min(Math.max(0, offset), buffer.length)).toString("utf8");
+  } catch {
+    return "";
+  }
+}
+
+function tailLine(text, cap = 240) {
+  const lines = String(text || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return lines.length ? lines[lines.length - 1].slice(0, cap) : "";
+}
+
+/**
+ * Wait for a just-spawned daemon to prove it is up.
+ *
+ * A pid from `spawn` is not a running runner: registration can be rejected, the
+ * token can be dead, the stream can refuse the connection, and every one of those
+ * exits within a second or two of a "Runner running (pid …)" line nobody had any
+ * reason to doubt. The log offset is taken before the spawn so an earlier
+ * daemon's "connected" line cannot be mistaken for this one's.
+ */
+export async function confirmRunnerOnline({ pid, offset = 0, timeoutMs = 12_000, intervalMs = 250 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const fresh = runnerLogSince(offset);
+    if (/connected as runner/.test(fresh)) return { state: "online", detail: "" };
+    if (!runnerIsAlive(pid)) return { state: "exited", detail: tailLine(fresh) };
+    if (Date.now() >= deadline) return { state: "starting", detail: tailLine(fresh) };
+    await sleep(intervalMs);
+  }
+}
+
 /** Start the daemon detached, so a terminal can be closed without killing it. */
 export function startBackground(commandArgs) {
   ensureDir();
+  const offset = logSize();
   // 0600 like everything else under ~/.preman: nothing in here is a credential
   // today, and that is not a property to leave depending on future log lines.
   const log = openSync(RUNNER_LOG_FILE, "a", 0o600);
@@ -753,7 +830,7 @@ export function startBackground(commandArgs) {
   );
   child.unref();
   writeFileSync(RUNNER_PID_FILE, `${child.pid}\n`, { mode: 0o600 });
-  return { pid: child.pid, log: RUNNER_LOG_FILE };
+  return { pid: child.pid, log: RUNNER_LOG_FILE, offset };
 }
 
 async function startForeground(args, commandArgs) {
@@ -786,6 +863,16 @@ async function startForeground(args, commandArgs) {
   process.on("SIGINT", () => void shutdown("SIGINT"));
   process.on("SIGTERM", () => void shutdown("SIGTERM"));
 
+  // A daemon that dies must not leave its pid file behind claiming otherwise.
+  // Nothing is swallowed: the reason is logged and the exit code says it failed.
+  const die = (kind) => (error) => {
+    log(`${kind}: ${error?.stack || error}`);
+    rmSync(RUNNER_PID_FILE, { force: true });
+    process.exit(1);
+  };
+  process.on("uncaughtException", die("uncaught exception"));
+  process.on("unhandledRejection", die("unhandled rejection"));
+
   try {
     const result = await runnerLoop(args, state, {
       log,
@@ -827,10 +914,20 @@ export async function runnerCommand(commandArgs = []) {
         return { state: "running", pid: readPid() };
       }
       const started = startBackground(commandArgs.filter((value) => value !== "start"));
+      const up = await confirmRunnerOnline(started);
+      if (up.state === "exited") {
+        rmSync(RUNNER_PID_FILE, { force: true });
+        process.stdout.write(
+          `Runner exited right after starting.\n` +
+            (up.detail ? `  ${up.detail}\n` : "") +
+            `  log: ${started.log}\n`
+        );
+        return { ...started, state: "exited" };
+      }
       process.stdout.write(
-        `Runner started in the background (pid ${started.pid}).\n  log: ${started.log}\n`
+        `Runner ${up.state === "online" ? "online" : "starting"} (pid ${started.pid}).\n  log: ${started.log}\n`
       );
-      return started;
+      return { ...started, state: up.state };
     }
     await startForeground(args, commandArgs);
     return { state: "stopped" };

package/bin/shared.js

@@ -8,7 +8,15 @@
  */
 
 import { spawn, spawnSync } from "node:child_process";
-import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+  mkdirSync,
+} from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -29,16 +37,55 @@ export const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
  */
 let _invocation = null;
 
-export function cliInvocation() {
-  if (_invocation) return _invocation;
+/**
+ * The package that owns the first `preman` on PATH, or "".
+ *
+ * `preman` is not ours by name alone: `preman-sdk` publishes a bin called
+ * exactly that, and whichever package lost the race still resolves. Assuming it
+ * is us writes hints and a git hook that call the other CLI — which answers
+ * "Unknown command: verify" and turns every push into a silent
+ * "[preman] checks skipped", the worst possible failure for a tool whose whole
+ * job is running checks on push.
+ */
+export function pathPremanOwner() {
   const probe = process.platform === "win32" ? "where" : "which";
+  let resolved = "";
   try {
     const found = spawnSync(probe, ["preman"], { stdio: "pipe", encoding: "utf8" });
-    _invocation = found.status === 0 && found.stdout.trim() ? "preman" : null;
+    if (found.status !== 0) return "";
+    resolved = String(found.stdout || "").split("\n")[0].trim();
   } catch {
-    _invocation = null;
+    return "";
   }
-  return (_invocation ||= "npm exec -y premanmcp@latest --");
+  if (!resolved) return "";
+
+  // Walk up from the real file, not the symlink: a bin is a link into the
+  // package directory, and only that directory's manifest names the owner.
+  try {
+    let dir = path.dirname(realpathSync(resolved));
+    for (let depth = 0; depth < 5; depth += 1) {
+      const manifest = path.join(dir, "package.json");
+      if (existsSync(manifest)) {
+        return String(JSON.parse(readFileSync(manifest, "utf8")).name || "");
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    return "";
+  }
+  return "";
+}
+
+export function cliInvocation() {
+  return (_invocation ||=
+    pathPremanOwner() === "premanmcp" ? "preman" : "npm exec -y premanmcp@latest --");
+}
+
+/** Test seam: `cliInvocation` memoizes a PATH probe for the life of the process. */
+export function resetCliInvocation() {
+  _invocation = null;
 }
 
 export function makeArgs(commandArgs = []) {

package/dist/server.js

@@ -1043,6 +1043,7 @@ export function createServer() {
                             backend_url: BACKEND_URL,
                             frontend_base_url: FRONTEND_BASE,
                             endpoints_page_url: buildAgentDashboardUrl("/endpoints"),
+                            config: configSource(),
                             message: "Not authenticated. Run `npm exec -y premanmcp@latest -- login`, or use user_auth_* then preman_create_api_key, or run preman_login.",
                         }),
                     }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {
@@ -13,9 +13,9 @@
     "dev": "tsx src/server.ts",
     "open-mcp-preview": "node scripts/emit-mcp-preview.mjs",
     "open-mcp-preview-in-cursor": "node scripts/open-cursor-preview.mjs",
-    "test": "npm run test:connect && npm run test:node",
+    "test": "npm run build && npm run test:connect && npm run test:node",
     "test:connect": "node scripts/smoke-connect.mjs",
-    "test:node": "node --test --test-timeout=30000 scripts/smoke-launcher-config.mjs scripts/smoke-onboard.mjs scripts/smoke-local-detect.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs"
+    "test:node": "node --test --test-timeout=30000 scripts/smoke-launcher-config.mjs scripts/smoke-runner.mjs scripts/smoke-repo-config.mjs scripts/smoke-onboard.mjs scripts/smoke-local-detect.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-cli-identity.mjs scripts/smoke-runner-heartbeat.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^0.1.0",