premanmcp 0.10.3 → 0.10.5

package/README.md

@@ -64,21 +64,28 @@ and then retries from your home directory, where the override cannot reach it
 first, then your agent. Agents you start in the overriding directory keep using its
 backend, which is the point of the file.
 
-Once linked, `connect` finishes onboarding without handing you homework:
+Once linked, `connect` installs the git pre-push hook — so `git push` checks the endpoints
+you touched — prints what is left, and stops. It asks nothing. Everything else it used to
+run is its own command, because each one can fail on its own and none of them should hold
+up a link that already worked:
 
-| Step | What happens |
-|------|--------------|
-| Endpoints | Runs your agent on the discovery brief, then reports `N endpoints · M runnable` |
-| First test | Generates and runs scenarios against the first runnable request |
-| Runner | Pairs this machine and starts `preman runner` in the background, so PreMan can apply fixes here instead of only describing them |
-| Desktop app | Offers the macOS app for watching runs and endpoints |
-| Integrations | Shows GitHub / AWS / Slack, opens what is missing, and picks the connection up when you finish in the browser or the desktop app |
-| Testing on push | Installs the git pre-push hook, so `git push` checks the endpoints you touched |
+```bash
+preman endpoints discover          # map this repo's endpoints
+preman runner start --background   # let PreMan apply fixes on this machine
+preman github                      # or connect it in the dashboard
+preman status                      # which of those are done
+```
+
+`preman onboard` (or `setup`) is the prompted walk through all of it — sign in, coding
+agent, endpoints, runner, GitHub, AWS, Slack — one question per step, `b` to go back, and a
+summary at the end. `connect --guide` runs the old full pass inside connect itself:
+discovery, a first test, the runner, the desktop app and the integration prompts.
 
 Useful flags: `--agent cursor|claude-code|codex` skips the picker, `--project` writes
-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.
+project-local config, `--print` shows the config without writing it, `--no-hook` leaves
+push testing alone, and `--no-guide` connects and nothing else. With `--guide`, `--yes`
+takes every step's default without asking and `--no-runner` / `--no-desktop` /
+`--no-integrations` 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`
@@ -218,9 +225,26 @@ npm exec -y premanmcp@latest -- login   # Create/login and generate a PreMan API
 npm exec -y premanmcp@latest -- install # Cursor-only installer (legacy)
 ```
 
+### Push testing
+
+```bash
+preman hook install         # Write the pre-push hook (connect does this too)
+preman hook status          # Installed? And does the command in it still answer?
+preman hook uninstall       # Remove it, restoring any hook it replaced
+```
+
+The hook is generated shell that runs `preman verify --pre-push` and can only ever be
+advisory: no backend, no credentials, a crash or a timeout all exit 0 with a notice. Before
+writing it, `install` runs the command it is about to embed and requires an answer — a hook
+holding a `preman` that belongs to another package prints `checks skipped` at every push and
+looks installed forever. The embedded command is pinned to the version that wrote it rather
+than `@latest`, so upgrading us never changes what your pushes run; re-run `hook install`
+to move it. Set `PREMAN_HOOK_INVOCATION` to write a command of your own instead, and
+`PREMAN_SKIP_HOOK=1` to silence the hook for a push.
+
 ### Runner
 
-`connect` sets this up for you; these are for managing it afterwards.
+`connect --guide` sets this up for you; these are for managing it afterwards.
 
 ```bash
 preman runner status              # Paired? Running?

package/bin/account.js

@@ -11,6 +11,7 @@ import { existsSync, rmSync } from "node:fs";
 import os from "node:os";
 
 import { detectCandidates } from "./detect.js";
+import { hookStatus } from "./hook.js";
 import {
   CREDENTIALS_FILE,
   backendUrl,
@@ -150,6 +151,39 @@ export async function doctorCommand(commandArgs = []) {
     )
   );
 
+  // An installed hook whose command no longer answers is the one failure here
+  // that reports itself as success everywhere else: `git push` prints a single
+  // skipped line and nothing else ever mentions it.
+  const hook = (() => {
+    try {
+      return hookStatus({ probe: true });
+    } catch {
+      return null; // not a git repository
+    }
+  })();
+  if (hook && hook.state === "installed") {
+    results.push(
+      line(
+        "push hook",
+        hook.works,
+        hook.works
+          ? `${hook.invocation}${hook.current ? "" : ` — out of date, run \`${cliInvocation()} hook install --force\``}`
+          : `${hook.invocation || "unreadable"} does not answer — run \`${cliInvocation()} hook install --force\``
+      )
+    );
+    if (!hook.works) failures += 1;
+  } else if (hook) {
+    results.push(
+      line(
+        "push hook",
+        null,
+        hook.state === "foreign"
+          ? "another tool owns pre-push here"
+          : `not installed — run \`${cliInvocation()} hook install\``
+      )
+    );
+  }
+
   if (status?.ok) {
     const integrations = status.integrations || {};
     for (const [name, section] of Object.entries(integrations)) {

package/bin/cli.js

@@ -21,6 +21,7 @@ import {
   CONNECT_HELP,
   DISPATCH_HELP,
   connectCommand,
+  discoverEndpoints,
   dispatchCommand,
   writeCursorConfig,
 } from "./connect.js";
@@ -84,7 +85,7 @@ function printHelp() {
     ["runner start|status|stop", "Run PreMan's queued agent work on this machine"],
     ["doctor", "Diagnose credentials, backend, target, integrations"],
     ["install-desktop", "Download and install the PreMan desktop app"],
-    ["onboard", "Sign in, then connect agent, GitHub, AWS, Slack"],
+    ["onboard", "Sign in, then agent, endpoints, runner, GitHub, AWS, Slack"],
     ["connect [options]", "Pick a coding agent and connect it"],
     ["dispatch [options]", "Let PreMan start agent runs for you"],
     ["aws | github | slack", "Connect one integration on its own"],
@@ -240,7 +241,13 @@ async function main() {
   } else if (command === "onboard" || command === "setup") {
     // makeArgs/authenticateTerminal/connectCommand are injected rather than
     // imported there, so integrations.js stays free of a cycle back into the CLI.
-    await onboardCommand(commandArgs, { makeArgs, authenticateTerminal, connectCommand });
+    await onboardCommand(commandArgs, {
+      makeArgs,
+      authenticateTerminal,
+      connectCommand,
+      discoverEndpoints,
+      runnerCommand,
+    });
   } else if (command === "aws") {
     await awsCommand(makeArgs(commandArgs));
   } else if (command === "github") {

package/bin/connect.js

@@ -21,6 +21,7 @@ import { installHook, hookStatus } from "./hook.js";
 import { MARK, awsCommand, githubCommand, slackCommand } from "./integrations.js";
 import {
   confirmRunnerOnline,
+  pairingIsLive,
   readRunnerState,
   registerRunner,
   runnerIsAlive,
@@ -1060,6 +1061,26 @@ function nextStepsBlock(agent) {
   );
 }
 
+/**
+ * What is left once the link is done, as commands rather than as questions.
+ *
+ * Connect used to run all of these itself, which bought a prompt per step and a
+ * wait as long as the slowest broken one — and a link that had already succeeded
+ * ended on a failed runner and a five-minute GitHub poll. Each is one command, so
+ * this lists them and gets out of the way.
+ */
+function whatIsLeftBlock(args) {
+  const cli = cliInvocation();
+  return (
+    "\nWhat is left:\n" +
+    `  ${cli} endpoints discover          # map this repo's endpoints\n` +
+    `  ${cli} runner start --background   # let PreMan apply fixes on this machine\n` +
+    `  ${cli} github                      # connect GitHub, or do it in the dashboard\n` +
+    `\n${cli} status reports your endpoints, last push and integrations.\n` +
+    `Watch runs at ${frontendUrl(args)}\n`
+  );
+}
+
 /**
  * Ask, or take the step's own default when nobody can answer.
  *
@@ -1130,7 +1151,7 @@ export function headlessDiscovery(agent, serverName, instructions = []) {
  *
  * Never throws: a failed discovery must not fail the connect.
  */
-async function discoverEndpoints(args, agent, serverName) {
+export async function discoverEndpoints(args, agent, serverName, blockedHere = "") {
   try {
     const before = await endpointCounts(args);
     if (before.registered) {
@@ -1142,7 +1163,10 @@ async function discoverEndpoints(args, agent, serverName) {
 
     const brief = await callPremanTool(args, "discover_endpoints_from_codebase", { base_path: "." });
     const spec = headlessDiscovery(agent, serverName, brief.instructions || []);
-    const blocker = spec && onPath(spec.bin) ? agentBlocker(agent.id) : "";
+    // Discovery has to read *this* repo, so it cannot be moved out of a directory
+    // that redirects it the way the check-in was — it can only be skipped, before
+    // it spends ten minutes proving what the self-test already found out.
+    const blocker = blockedHere || (spec && onPath(spec.bin) ? agentBlocker(agent.id) : "");
     if (!spec || !onPath(spec.bin) || blocker) {
       // Say why before printing homework: "here is a brief" reads as PreMan not
       // working, when the actual answer is one login away.
@@ -1238,6 +1262,24 @@ async function runFirstTest(args, runnable, { assumeYes }) {
   }
 }
 
+/**
+ * Whether a stored pairing can still be used, rather than merely matching.
+ *
+ * Matching agent and path only prove the state was written for this project. The
+ * token behind it can be revoked, replaced by another device, or left over from an
+ * API key that no longer exists — and reusing one of those starts a daemon that
+ * 401s on its first stream and exits, which reads as "the runner cannot start
+ * here" when the pairing is the only thing that needed replacing.
+ *
+ * A backend we cannot reach answers "usable": re-pairing is for a token the
+ * backend rejected, not for a network that was briefly down.
+ */
+export async function runnerPairingIsUsable(args, existing, agentId, { cwd = process.cwd() } = {}) {
+  if (!existing || existing.agent !== agentId) return false;
+  if (path.resolve(String(existing.project_path || "")) !== path.resolve(cwd)) return false;
+  return pairingIsLive(args, existing);
+}
+
 /**
  * Pair this machine as a runner and leave it running.
  *
@@ -1264,7 +1306,7 @@ async function setUpRunner(args, agent, { assumeYes }) {
   }
 
   try {
-    if (!existing || existing.agent !== agent.id || existing.project_path !== path.resolve(process.cwd())) {
+    if (!(await runnerPairingIsUsable(args, existing, agent.id))) {
       await registerRunner(args, { agent: agent.id, projectPath: process.cwd() });
     }
     const started = startBackground([]);
@@ -1406,7 +1448,7 @@ async function setUpPushTesting(args) {
   if (args.has("--no-hook")) return { state: "skipped" };
   const current = (() => {
     try {
-      return hookStatus();
+      return hookStatus({ probe: true });
     } catch {
       return null; // not a git repository
     }
@@ -1415,9 +1457,10 @@ async function setUpPushTesting(args) {
     process.stdout.write(`${MARK.skip()} Not a git repository — no push testing here.\n`);
     return { state: "unavailable" };
   }
-  // A hook whose invocation went stale is reinstalled rather than reported as on:
-  // it is the case where PreMan looks connected and silently checks nothing.
-  if (current.state === "installed" && current.current) {
+  // A hook whose invocation went stale, or no longer answers, is reinstalled
+  // rather than reported as on: it is the case where PreMan looks connected and
+  // silently checks nothing.
+  if (current.state === "installed" && current.current && current.works) {
     process.stdout.write(`${MARK.ok()} Push testing already on.\n`);
     return { state: "installed" };
   }
@@ -1429,6 +1472,13 @@ async function setUpPushTesting(args) {
     );
     return result;
   }
+  if (result.action === "unproven") {
+    process.stdout.write(
+      `${MARK.skip()} No push testing: ${result.detail}\n` +
+        `   Then: ${cliInvocation()} hook install\n`
+    );
+    return result;
+  }
   process.stdout.write(
     `${MARK.ok()} Push testing on — \`git push\` now checks the endpoints you touched.\n` +
       "   It never blocks a push; PREMAN_SKIP_HOOK=1 silences it.\n"
@@ -1437,16 +1487,18 @@ async function setUpPushTesting(args) {
 }
 
 /**
- * Everything after the link, in one pass, with nothing left for the user to run.
+ * Everything after the link, in one pass, for whoever asks for it with `--guide`.
  *
  * Order follows what a new account needs to see: what PreMan found, then where to
- * watch it, then who to tell, then when to run it.
+ * watch it, then who to tell, then when to run it. It is opt-in because running
+ * all of it unasked is what turned a finished connect into a screen of prompts,
+ * a dead runner and a five-minute wait on an integration nobody had asked for.
  */
-async function guidedFirstRun(args, agent, apiKey, serverName) {
+async function guidedFirstRun(args, agent, apiKey, serverName, { blockedHere = "" } = {}) {
   const assumeYes = args.has("--yes");
 
   step("Endpoints");
-  const counts = await discoverEndpoints(args, agent, serverName);
+  const counts = await discoverEndpoints(args, agent, serverName, blockedHere);
 
   if (counts.first) {
     step("First test");
@@ -1541,10 +1593,12 @@ Connect options:
   --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
+  --guide                     Also run discovery, the runner, the desktop app
+                              and the integration prompts after connecting
+  --no-guide                  Connect only: no push hook, no closing summary
+  --no-runner                 With --guide, do not pair this machine as a runner
+  --no-desktop                With --guide, do not offer the desktop app
+  --no-integrations           With --guide, do not offer GitHub / AWS / Slack
   --no-hook                   Do not install the git pre-push hook
   --yes                       Take every step's default without prompting
                               (the desktop app defaults to no; install-desktop)
@@ -1661,25 +1715,42 @@ export async function connectCommand(commandArgs) {
     return;
   }
 
-  if (
-    !(await establishCheckIn(args, agent, apiKey, {
-      serverName,
-      written,
-      serverConfig,
-      projectInstall,
-    }))
-  ) {
+  const checkIn = await establishCheckIn(args, agent, apiKey, {
+    serverName,
+    written,
+    serverConfig,
+    projectInstall,
+  });
+  // The agent goes back to the caller because `onboard` runs steps after this one
+  // that need to know which agent to drive, and asking twice is a question we
+  // already have the answer to.
+  const connected = { agent, serverName, linked: checkIn.linked };
+  if (!checkIn.linked) {
     // 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;
+    return connected;
   }
 
   process.stdout.write(`${MARK.ok()} Connected as ${agent.label}.\n`);
+
+  // Connecting is one job. Running discovery, pairing a runner, offering the
+  // desktop app and installing three integrations is five more, each with its
+  // own prompt and its own way to fail -- and a connect that ends in a failed
+  // runner and a five-minute GitHub poll reads as a broken product rather than a
+  // finished link. The push hook stays because it is the only one that is not a
+  // question: it is what makes PreMan run at all, and it costs a file write.
+  if (args.has("--guide") && !args.has("--no-guide")) {
+    await guidedFirstRun(args, agent, apiKey, serverName, { blockedHere: checkIn.blockedHere });
+    await captureDispatchCredential(args, agent, apiKey);
+    return connected;
+  }
   if (!args.has("--no-guide")) {
-    await guidedFirstRun(args, agent, apiKey, serverName);
+    await setUpPushTesting(args);
+    process.stdout.write(whatIsLeftBlock(args));
   }
-  await captureDispatchCredential(args, agent, apiKey);
+  await captureDispatchCredential(args, agent, apiKey, { prompt: false });
+  return connected;
 }
 
 /**
@@ -1744,8 +1815,10 @@ export function neutralCwd(candidates = [os.homedir(), os.tmpdir()]) {
  * 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.
+ * Returns whether the check-in landed and, when this directory redirects it, why
+ * nothing started here can use PreMan — the caller has its own agent to run once
+ * this is done. Prints the troubleshooting block itself when the link did not
+ * land.
  */
 async function establishCheckIn(
   args,
@@ -1754,9 +1827,11 @@ async function establishCheckIn(
   { serverName, written, serverConfig, projectInstall = false }
 ) {
   const notes = [];
-  // Set only when this directory would redirect the agent, and then it is where
-  // the agent gets started instead.
+  // Both set only when this directory redirects the agent: where it can be
+  // started instead, and why an agent left standing here cannot use PreMan at all.
   let elsewhere = null;
+  let blockedHere = "";
+  const done = (linked) => ({ linked, blockedHere });
   const ticker = pollTicker();
   const say = (text) => {
     ticker.end();
@@ -1781,7 +1856,7 @@ async function establishCheckIn(
       );
     }
     if (test.ok && status.authenticated && (await waitForConnection(args, apiKey, { timeoutMs: 15000 }))) {
-      return true;
+      return done(true);
     }
     note(
       test.ok
@@ -1806,6 +1881,12 @@ async function establishCheckIn(
           `directory forces: ${cliInvocation()} connect ${flag} --backend ${redirect.actual} ` +
           `(needs a key issued by it, and that API running).`
       );
+      // Linking is not the only thing this directory breaks: whatever runs here
+      // next gets the same redirected, unauthenticated server, and the callers
+      // that would start an agent in it need to hear so.
+      blockedHere =
+        `${redirect.path} sends ${agent.label} to ${redirect.actual} in this directory, ` +
+        `where this key is not valid.`;
 
       // The config we wrote is correct; the directory around it is not. Since the
       // server only reads the file it is standing in, everything this does next
@@ -1813,7 +1894,7 @@ async function establishCheckIn(
       const outside = neutralCwd();
       if (!outside) {
         notLinked(`Run '${cliInvocation()} connect' from your own project instead of this directory.`);
-        return false;
+        return done(false);
       }
 
       say(
@@ -1834,7 +1915,7 @@ async function establishCheckIn(
         retry.status?.authenticated &&
         (await waitForConnection(args, apiKey, { timeoutMs: 15000 }))
       ) {
-        return true;
+        return done(true);
       }
 
       if (projectInstall) {
@@ -1845,7 +1926,7 @@ async function establishCheckIn(
           `This --project config exists only here; started anywhere else, ` +
             `${agent.label} has no ${serverName} server to call.`
         );
-        return false;
+        return done(false);
       }
       elsewhere = outside;
     }
@@ -1867,7 +1948,7 @@ async function establishCheckIn(
     });
     if (launch.connected) {
       ticker.end();
-      return true;
+      return done(true);
     }
     if (launch.ran && !launch.interactive) {
       const why = lastLine(launch.output);
@@ -1896,7 +1977,7 @@ async function establishCheckIn(
 
   if (await waitForConnection(args, apiKey, { onPoll: ticker.tick })) {
     ticker.end();
-    return true;
+    return done(true);
   }
 
   say(
@@ -1907,5 +1988,5 @@ async function establishCheckIn(
       `  - 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;
+  return done(false);
 }

package/bin/hook.js

@@ -12,20 +12,22 @@ import { spawnSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
 
-import { cliInvocation, makeArgs } from "./shared.js";
+import { cliInvocation, makeArgs, packageVersion } from "./shared.js";
 import { BLOCK_EXIT_CODE } from "./verify.js";
 
 export const HOOK_HELP = `
 Hook options:
   install               Write the pre-push hook into this repository
   uninstall             Remove PreMan's pre-push hook
-  status                Report whether the hook is installed
+  status                Report whether the hook is installed, and still works
   --force               Overwrite a foreign pre-push hook (a backup is kept)
+  PREMAN_HOOK_INVOCATION=<cmd>  Use this command line instead of probing for one
 `;
 
 const MARKER = "# >>> preman pre-push >>>";
 const END_MARKER = "# <<< preman pre-push <<<";
 const HOOK_TIMEOUT_SECONDS = 120;
+const PROBE_TIMEOUT_MS = 45000;
 
 function gitDir() {
   const result = spawnSync("git", ["rev-parse", "--git-dir"], { encoding: "utf8" });
@@ -39,7 +41,90 @@ function hookPath() {
   return path.join(gitDir(), "hooks", "pre-push");
 }
 
-function hookBody() {
+/**
+ * The command lines a hook could carry, best first.
+ *
+ * A hook is written once and read at every push, so `@latest` quietly hands each
+ * push to whatever we ship next; the version that wrote the hook is the one that
+ * keeps running it, and `preman hook install` is how that moves. `@latest` is
+ * left only for the case where we cannot read our own manifest to know it.
+ *
+ * The bare `preman` form is offered first when it is ours — see `pathPremanOwner`
+ * — because it starts in milliseconds where npm exec does not.
+ */
+export function hookInvocations() {
+  const version = packageVersion();
+  const pinned = `npm exec -y premanmcp@${version || "latest"} --`;
+  const preferred = cliInvocation();
+  return preferred.startsWith("npm exec") ? [pinned] : [preferred, pinned];
+}
+
+const probed = new Map();
+
+/** An invocation the user pinned by hand, or "". */
+function declaredInvocation() {
+  return String(process.env.PREMAN_HOOK_INVOCATION || "").trim();
+}
+
+/**
+ * Does this command line reach a PreMan CLI that knows `verify`, from a process
+ * that is not this one?
+ *
+ * This is the check whose absence produced `Unknown command: verify` on every
+ * push: the hook is generated shell run minutes or months later, so the only
+ * evidence that matters is a separate process answering. `help` is the cheapest
+ * subcommand that proves both halves — that something ran, and that it was us
+ * rather than another package's identically named `preman`.
+ *
+ * Memoized per command line, because a connect installs and then re-reads the
+ * hook, and npm exec is slow enough that paying twice shows.
+ */
+export function invocationAnswers(invocation) {
+  // Declaring an invocation means "use this and stop asking", so the same answer
+  // has to hold when we later read it back out of a hook -- otherwise the escape
+  // hatch writes a hook that every status then calls broken.
+  if (invocation && invocation === declaredInvocation()) return true;
+  if (probed.has(invocation)) return probed.get(invocation);
+  let answered = false;
+  try {
+    const probe = spawnSync(`${invocation} help`, {
+      shell: true,
+      encoding: "utf8",
+      timeout: Number(process.env.PREMAN_HOOK_PROBE_MS) || PROBE_TIMEOUT_MS,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    answered = probe.status === 0 && /\bverify\b/.test(String(probe.stdout || ""));
+  } catch {
+    answered = false;
+  }
+  probed.set(invocation, answered);
+  return answered;
+}
+
+/** Test seam: the probe above is memoized for the life of the process. */
+export function resetInvocationProbe() {
+  probed.clear();
+}
+
+/**
+ * The invocation to write into a hook, or "" when nothing here can run PreMan.
+ *
+ * `PREMAN_HOOK_INVOCATION` is taken on trust: it exists for the setups we cannot
+ * probe our way to — a wrapper script, a monorepo runner, a pinned mirror.
+ */
+export function provenInvocation() {
+  return (
+    declaredInvocation() || hookInvocations().find((candidate) => invocationAnswers(candidate)) || ""
+  );
+}
+
+/** The command line an already-written hook calls, or "". */
+function embeddedInvocation(text) {
+  const match = /^\s*PREMAN_HOOK=1 (.+) verify --pre-push\b/m.exec(text);
+  return match ? match[1].trim() : "";
+}
+
+function hookBody(invocation) {
   // `exec` is deliberately absent: we want the wrapper to survive the CLI exiting
   // non-zero and still exit 0 itself.
   //
@@ -51,7 +136,7 @@ ${MARKER}
 # Advisory unless this repository opted into blocking: only exit code
 # ${BLOCK_EXIT_CODE} stops a push, so a crash or a timeout still lets it through.
 if [ -z "\${PREMAN_SKIP_HOOK}" ]; then
-  PREMAN_HOOK=1 ${cliInvocation()} verify --pre-push --timeout ${HOOK_TIMEOUT_SECONDS}
+  PREMAN_HOOK=1 ${invocation} verify --pre-push --timeout ${HOOK_TIMEOUT_SECONDS}
   preman_status=$?
   if [ "$preman_status" -eq ${BLOCK_EXIT_CODE} ]; then
     exit ${BLOCK_EXIT_CODE}
@@ -71,16 +156,31 @@ function isOurHook(text) {
   return text.includes(MARKER);
 }
 
-export function installHook(args) {
+export function installHook(args, { invocation = provenInvocation() } = {}) {
   const target = hookPath();
+
+  // A hook holding a command that does not run is worse than no hook: it is
+  // silent, it says "installed" in every status we print, and the only sign of
+  // it is one skipped line scrolling past a push nobody reads.
+  if (!invocation) {
+    return {
+      path: target,
+      action: "unproven",
+      detail:
+        "no way to run the PreMan CLI from a hook was found here" +
+        " -- install it globally (npm i -g premanmcp) or set PREMAN_HOOK_INVOCATION",
+    };
+  }
+
+  const body = hookBody(invocation);
   mkdirSync(path.dirname(target), { recursive: true });
 
   if (existsSync(target)) {
     const existing = readFileSync(target, "utf8");
     if (isOurHook(existing)) {
-      writeFileSync(target, hookBody(), { mode: 0o755 });
+      writeFileSync(target, body, { mode: 0o755 });
       chmodSync(target, 0o755);
-      return { path: target, action: "updated" };
+      return { path: target, action: "updated", invocation };
     }
     if (!args.has("--force")) {
       return {
@@ -91,14 +191,19 @@ export function installHook(args) {
     }
     const backup = `${target}.preman-backup`;
     writeFileSync(backup, existing, { mode: 0o755 });
-    writeFileSync(target, hookBody(), { mode: 0o755 });
+    writeFileSync(target, body, { mode: 0o755 });
     chmodSync(target, 0o755);
-    return { path: target, action: "replaced", detail: `previous hook saved to ${backup}` };
+    return {
+      path: target,
+      action: "replaced",
+      invocation,
+      detail: `previous hook saved to ${backup}`,
+    };
   }
 
-  writeFileSync(target, hookBody(), { mode: 0o755 });
+  writeFileSync(target, body, { mode: 0o755 });
   chmodSync(target, 0o755);
-  return { path: target, action: "installed" };
+  return { path: target, action: "installed", invocation };
 }
 
 export function uninstallHook() {
@@ -122,17 +227,36 @@ export function uninstallHook() {
  * `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.
+ * stale — the machine gained a `preman` that is not ours, lost the one that was,
+ * or upgraded past the version the hook pins. "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.
+ *
+ * `works` answers the harder question — does the command in the file still run
+ * PreMan — so callers ask for it: `preman hook status` and `preman doctor` do,
+ * connect does not. Both answers cost a probe for an installed hook, since
+ * "up to date" means "equal to what we would write now", and what we would write
+ * is whatever answers here. An absent or foreign hook costs nothing.
  */
-export function hookStatus() {
+export function hookStatus({ probe = false } = {}) {
   const target = hookPath();
-  if (!existsSync(target)) return { path: target, state: "absent", current: false };
+  const missing = { path: target, current: false, invocation: "", works: null };
+  if (!existsSync(target)) return { ...missing, state: "absent" };
   const existing = readFileSync(target, "utf8");
-  if (!isOurHook(existing)) return { path: target, state: "foreign", current: false };
-  return { path: target, state: "installed", current: existing === hookBody() };
+  if (!isOurHook(existing)) return { ...missing, state: "foreign" };
+
+  const invocation = embeddedInvocation(existing);
+  // Falling back to what the file already carries keeps a machine that can no
+  // longer prove any invocation -- offline, say -- from reporting a hook as out
+  // of date and sending its owner to a reinstall that would refuse to write.
+  const wanted = provenInvocation() || invocation;
+  return {
+    path: target,
+    state: "installed",
+    invocation,
+    current: Boolean(wanted) && existing === hookBody(wanted),
+    works: probe ? Boolean(invocation) && invocationAnswers(invocation) : null,
+  };
 }
 
 export async function hookCommand(commandArgs = []) {
@@ -141,13 +265,14 @@ export async function hookCommand(commandArgs = []) {
 
   if (sub === "install") {
     const result = installHook(args);
-    if (result.action === "conflict") {
+    if (result.action === "conflict" || result.action === "unproven") {
       process.stdout.write(`Not installed: ${result.detail}\n  ${result.path}\n`);
       return result;
     }
     process.stdout.write(
       `Pre-push hook ${result.action}: ${result.path}\n` +
         (result.detail ? `  ${result.detail}\n` : "") +
+        `  Runs: ${result.invocation} verify --pre-push\n` +
         `\nPreMan will now check affected endpoints before each push.\n` +
         `It never blocks a push -- set PREMAN_SKIP_HOOK=1 to silence it entirely.\n`
     );
@@ -163,13 +288,27 @@ export async function hookCommand(commandArgs = []) {
   }
 
   if (sub === "status") {
-    const result = hookStatus();
+    const result = hookStatus({ probe: true });
     const label = {
       installed: "installed (PreMan)",
       foreign: "present, but not written by PreMan",
       absent: "not installed",
     }[result.state];
     process.stdout.write(`Pre-push hook: ${label}\n  ${result.path}\n`);
+    if (result.state === "installed") {
+      process.stdout.write(`  Runs: ${result.invocation || "(unreadable)"}\n`);
+      // "Installed" was never the question -- a hook that cannot reach the CLI
+      // prints one skipped line per push and is otherwise indistinguishable.
+      process.stdout.write(
+        result.works
+          ? "  That command answers here.\n"
+          : `  That command does not answer here -- pushes are being skipped.\n` +
+              `    Repair it: ${cliInvocation()} hook install --force\n`
+      );
+      if (!result.current) {
+        process.stdout.write(`  Out of date: ${cliInvocation()} hook install --force\n`);
+      }
+    }
     return result;
   }
 

package/bin/integrations.js

@@ -26,6 +26,12 @@ import {
 
 const POLL_INTERVAL_MS = 3000;
 const POLL_TIMEOUT_MS = 300000;
+// GitHub is the one install where waiting longer buys nothing. A CloudFormation
+// stack genuinely takes minutes, but the App either redirects back seconds after
+// the customer confirms or it never does — and five more minutes of dots turns a
+// hand-off into an outage. PREMAN_GITHUB_POLL_MS shortens it, so a test of the
+// hand-off does not have to spend three quarters of a minute reaching it.
+const GITHUB_POLL_TIMEOUT_MS = 45000;
 
 /**
  * Colour only when someone is actually watching.
@@ -75,9 +81,13 @@ 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, { hint = "", hintAfterMs = 60000 } = {}) {
+async function waitFor(
+  label,
+  check,
+  { hint = "", hintAfterMs = 60000, timeoutMs = POLL_TIMEOUT_MS } = {}
+) {
   const startedAt = Date.now();
-  const deadline = startedAt + POLL_TIMEOUT_MS;
+  const deadline = startedAt + timeoutMs;
   let hinted = false;
   process.stdout.write(`Waiting for ${label}`);
   while (Date.now() < deadline) {
@@ -232,6 +242,10 @@ export async function githubCommand(args) {
   present(url, "install the PreMan GitHub App");
   process.stdout.write("Pick the repositories PreMan may read.\n");
 
+  // The refresh answer is the diagnosis. A 409 means GitHub never called back;
+  // a success carrying no repositories means the App is installed and sharing
+  // nothing — two dead ends that are indistinguishable from the repository list.
+  let refresh = null;
   const done = await waitFor(
     "the installation",
     async () => {
@@ -239,7 +253,7 @@ export async function githubCommand(args) {
       // 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", {
+      refresh = await callBackendJson(args, "POST", "/integrations/github/app/refresh", {
         token,
         json: {},
       });
@@ -249,24 +263,46 @@ export async function githubCommand(args) {
       return fresh.length ? fresh : null;
     },
     {
+      timeoutMs: Number(process.env.PREMAN_GITHUB_POLL_MS) || GITHUB_POLL_TIMEOUT_MS,
+      hintAfterMs: 20000,
       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.",
+        "Still nothing from GitHub. Picking at least one repository and confirming\n" +
+        "is what sends you back here.",
     }
   );
 
   if (!done) {
-    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`
-    );
+    process.stdout.write(githubHandOff(args, refresh));
     return;
   }
   connected(`GitHub connected: ${done.length} repository(ies).`);
   for (const repo of done.slice(0, 5)) process.stdout.write(`  - ${repo.repo_url}\n`);
 }
 
+/**
+ * Stop waiting, and name the dead end instead of the timeout.
+ *
+ * Holding the terminal for five minutes taught nobody anything: the install
+ * finishes in the browser whether this process is watching or not, and the two
+ * ways it can complete and still leave PreMan with nothing are both actionable.
+ */
+function githubHandOff(args, refresh) {
+  const installed = Boolean(refresh?.ok) && Number(refresh.installations_refreshed || 0) > 0;
+  if (installed) {
+    return (
+      `The App is installed, but no repositories are shared with it.\n` +
+      `  - Add some: https://github.com/settings/installations\n` +
+      `  - Then re-run '${cliInvocation()} github'.\n`
+    );
+  }
+  return (
+    `Nothing from GitHub yet — no need to wait here.\n` +
+    `  - Finish the install in the browser; it records itself when you confirm.\n` +
+    `  - Check it: ${frontendUrl(args)}  or  https://github.com/settings/installations\n` +
+    `  - Then re-run '${cliInvocation()} github'.\n`
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Slack
 // ---------------------------------------------------------------------------
@@ -301,6 +337,17 @@ export async function slackCommand(args) {
 // The guided run
 // ---------------------------------------------------------------------------
 
+/**
+ * Why a step that needs a connected agent cannot run on its own.
+ *
+ * Both of these drive the agent `connect` just linked, so skipping that step
+ * leaves them without one -- which is a thing to say plainly, with the command
+ * that does it later, rather than a stack trace about a missing id.
+ */
+function needsAgent(command) {
+  return `no coding agent connected yet -- run '${cliInvocation()} connect', then '${cliInvocation()} ${command}'`;
+}
+
 /** "yes" | "no" | "back" -- back only offered once there is somewhere to go. */
 async function askStep(question, { assumeYes, canGoBack }) {
   if (assumeYes) return "yes";
@@ -319,7 +366,10 @@ async function askStep(question, { assumeYes, canGoBack }) {
  * throws is reported and the run continues rather than unwinding the ones that
  * already worked.
  */
-export async function onboardCommand(commandArgs, { makeArgs, authenticateTerminal, connectCommand }) {
+export async function onboardCommand(
+  commandArgs,
+  { makeArgs, authenticateTerminal, connectCommand, discoverEndpoints, runnerCommand }
+) {
   const args = makeArgs(commandArgs);
   const assumeYes = args.has("--yes");
 
@@ -328,11 +378,33 @@ export async function onboardCommand(commandArgs, { makeArgs, authenticateTermin
   const creds = await authenticateTerminal(args);
   connected(`Signed in as ${creds.user_email || "your account"}.`);
 
+  // Which agent the endpoints and runner steps drive. `connect` decided it, by
+  // detection or by asking, and this is the answer rather than a second prompt.
+  let linked = null;
+
   const steps = [
     {
       name: "coding agent",
       question: "Connect your coding agent?",
-      run: () => connectCommand([...commandArgs, "--skip-login"]),
+      run: async () => {
+        linked = (await connectCommand([...commandArgs, "--skip-login"])) || null;
+      },
+    },
+    {
+      name: "endpoints",
+      question: "Map this repository's endpoints?",
+      run: () => {
+        if (!linked?.agent) throw new Error(needsAgent("endpoints discover"));
+        return discoverEndpoints(args, linked.agent, linked.serverName);
+      },
+    },
+    {
+      name: "runner",
+      question: "Let PreMan run your agent here when it finds something to fix?",
+      run: () => {
+        if (!linked?.agent) throw new Error(needsAgent("runner start --background"));
+        return runnerCommand(["start", "--background", "--agent", linked.agent.id]);
+      },
     },
     { name: "GitHub", question: "Connect GitHub?", run: () => githubCommand(args) },
     { name: "AWS logs", question: "Connect AWS?", run: () => awsCommand(args) },
@@ -392,7 +464,8 @@ export async function onboardCommand(commandArgs, { makeArgs, authenticateTermin
 
 export const INTEGRATIONS_HELP = `
 Setup options:
-  preman onboard              Sign in, then connect agent, GitHub, AWS and Slack
+  preman onboard              Sign in, then agent, endpoints, runner, GitHub,
+                              AWS and Slack, one prompt per step
   preman aws                  Connect an AWS account and stream a log group
   preman github               Install the PreMan GitHub App
   preman slack                Add PreMan to a Slack workspace

package/bin/runner.js

@@ -608,6 +608,12 @@ export async function executeJob(args, state, job, { log = () => {}, fullAccess
 
 // ── Event loop ──────────────────────────────────────────────────────────
 
+/** The re-pairing command for this runner. `register` without --agent exits 2. */
+function repairCommand(state) {
+  const agent = String(state?.agent || "claude_code").replace(/_/g, "-");
+  return `${cliInvocation()} runner register --agent ${agent}`;
+}
+
 function defaultLog(message) {
   process.stdout.write(`[preman runner] ${new Date().toISOString()} ${message}\n`);
 }
@@ -682,7 +688,7 @@ export async function runnerLoop(
       }
 
       if (response.status === 401) {
-        log("runner token was revoked; re-pair with `preman runner register`");
+        log(`runner token was revoked; re-pair with \`${repairCommand(state)}\``);
         clearRunnerState();
         return { stopped: true, jobsRun, reason: "revoked" };
       }
@@ -729,7 +735,7 @@ export async function runnerLoop(
       }
 
       if (terminal === "revoked") {
-        log("runner was revoked; re-pair with `preman runner register`");
+        log(`runner was revoked; re-pair with \`${repairCommand(state)}\``);
         clearRunnerState();
         return { stopped: true, jobsRun, reason: "revoked" };
       }
@@ -815,6 +821,19 @@ export async function confirmRunnerOnline({ pid, offset = 0, timeoutMs = 12_000,
   }
 }
 
+/**
+ * Does the backend still honour this pairing's token?
+ *
+ * One heartbeat, which is the only call that can answer it. A backend we cannot
+ * reach answers yes: re-pairing is for a token that was rejected, not for a
+ * network that blinked, and registering again would spend a pair code to fix
+ * nothing.
+ */
+export async function pairingIsLive(args, state) {
+  const { revoked } = await sendHeartbeat(args, state, { log: () => {} });
+  return !revoked;
+}
+
 /** Start the daemon detached, so a terminal can be closed without killing it. */
 export function startBackground(commandArgs) {
   ensureDir();
@@ -844,6 +863,14 @@ async function startForeground(args, commandArgs) {
       );
     }
     state = await registerRunner(args, { agent, projectPath: args.value("--path", process.cwd()) });
+  } else if (!(await pairingIsLive(args, state))) {
+    // A stored pairing is not a working one. The backend revokes a runner when
+    // another device takes over, when the key behind it is deleted, or when this
+    // machine was last seen going offline -- and starting on one of those dies on
+    // the first stream call with a 401, which reads as "the runner cannot run
+    // here" when the token was the only thing that needed replacing.
+    defaultLog("stored pairing was rejected; registering this machine again");
+    state = await registerRunner(args, { agent: state.agent, projectPath: state.project_path });
   }
 
   const log = defaultLog;

package/bin/shared.js

@@ -20,6 +20,7 @@ import {
 import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
 
 export const DEFAULT_BACKEND = "https://api.preman.live";
 export const DEFAULT_FRONTEND = "https://app.preman.live";
@@ -38,7 +39,40 @@ export const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
 let _invocation = null;
 
 /**
- * The package that owns the first `preman` on PATH, or "".
+ * A `preman` that exists only for this process, and cannot be written down.
+ *
+ * `npm exec` prepends its cache's `node_modules/.bin` to the child's PATH, and
+ * this package declares a `preman` bin — so inside our own documented launcher,
+ * `which preman` finds *us*. Believing it produced a git hook calling `preman
+ * verify`, which worked in that one process and answered "Unknown command:
+ * verify" at every later `git push`, because the PATH entry was gone.
+ *
+ * A durable global install (`npm i -g premanmcp`) is not under an `_npx` cache,
+ * so it still counts.
+ */
+function isEphemeralBin(realPath) {
+  return realPath.split(path.sep).includes("_npx");
+}
+
+/** The package owning a resolved bin, by the nearest manifest above it, or "". */
+function owningPackage(realPath) {
+  // 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.
+  let dir = path.dirname(realPath);
+  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;
+  }
+  return "";
+}
+
+/**
+ * The package that owns the `preman` a *later* process would find, 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
@@ -46,34 +80,36 @@ let _invocation = null;
  * "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.
+ *
+ * Every match is considered, not just the first: an ephemeral hit shadowing a
+ * real global install must not decide the answer for either of them.
  */
 export function pathPremanOwner() {
-  const probe = process.platform === "win32" ? "where" : "which";
-  let resolved = "";
+  const onWindows = process.platform === "win32";
+  let candidates = [];
   try {
-    const found = spawnSync(probe, ["preman"], { stdio: "pipe", encoding: "utf8" });
+    const found = spawnSync(onWindows ? "where" : "which", onWindows ? ["preman"] : ["-a", "preman"], {
+      stdio: "pipe",
+      encoding: "utf8",
+    });
     if (found.status !== 0) return "";
-    resolved = String(found.stdout || "").split("\n")[0].trim();
+    candidates = String(found.stdout || "")
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
   } catch {
     return "";
   }
-  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;
+  for (const candidate of candidates) {
+    try {
+      const realPath = realpathSync(candidate);
+      if (isEphemeralBin(realPath)) continue;
+      const owner = owningPackage(realPath);
+      if (owner) return owner;
+    } catch {
+      // A dangling link or an unreadable manifest: try the next match.
     }
-  } catch {
-    return "";
   }
   return "";
 }
@@ -83,6 +119,16 @@ export function cliInvocation() {
     pathPremanOwner() === "premanmcp" ? "preman" : "npm exec -y premanmcp@latest --");
 }
 
+/** The version of the package this process is running from, or "". */
+export function packageVersion() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return String(JSON.parse(readFileSync(path.join(here, "..", "package.json"), "utf8")).version || "");
+  } catch {
+    return "";
+  }
+}
+
 /** Test seam: `cliInvocation` memoizes a PATH probe for the life of the process. */
 export function resetCliInvocation() {
   _invocation = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {