premanmcp 0.10.4 → 0.10.6

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" };
       }
@@ -759,8 +765,9 @@ async function goOffline(args, state, log = defaultLog) {
 
 export const RUNNER_HELP = `
 Runner options:
-  runner start [--background]   Hold the job stream and run queued work here
-  runner register [--agent a]   Pair this machine as a runner (connect does this)
+  runner start [--background]   Hold the job stream and run queued work here,
+                                pairing this machine first if it is not paired
+  runner register [--agent a]   Pair without starting (start does this for you)
   runner status                 Report whether the local runner is running
   runner stop                   Stop the background runner and go offline
   --agent <name>                claude-code | cursor | codex
@@ -815,6 +822,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();
@@ -839,11 +859,21 @@ async function startForeground(args, commandArgs) {
     const agent = normalizeAgentId(args.value("--agent", "")) || "";
     if (!agent) {
       throw new RunnerError(
-        `This machine is not paired as a runner yet. Run '${cliInvocation()} runner register --agent claude-code'.`,
+        "This machine is not paired as a runner yet, and which agent to pair as could not be" +
+          ` worked out here. Say so directly: '${cliInvocation()} runner start --background` +
+          " --agent cursor|claude-code|codex'.",
         2
       );
     }
     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;
@@ -888,9 +918,22 @@ async function startForeground(args, commandArgs) {
   }
 }
 
-export async function runnerCommand(commandArgs = []) {
+export async function runnerCommand(commandArgs = [], { resolveAgent = null } = {}) {
   const sub = commandArgs.find((value) => !value.startsWith("-")) || "status";
-  const args = makeArgs(commandArgs);
+  let args = makeArgs(commandArgs);
+
+  // Pairing needs an agent id, and the only place that can be asked for one is
+  // here: `--background` hands the work to a detached child with no terminal, so
+  // a question deferred to it is a question nobody ever sees.
+  if ((sub === "register" || sub === "start") && resolveAgent && !args.value("--agent", "")) {
+    if (sub === "register" || !readRunnerState()) {
+      const resolved = await resolveAgent();
+      if (resolved) {
+        commandArgs = [...commandArgs, "--agent", resolved];
+        args = makeArgs(commandArgs);
+      }
+    }
+  }
 
   if (sub === "register") {
     const agent = normalizeAgentId(args.value("--agent", ""));
@@ -939,7 +982,7 @@ export async function runnerCommand(commandArgs = []) {
     const alive = runnerIsAlive(pid);
     if (!state) {
       process.stdout.write(
-        `Local runner: not paired\n  Pair it: ${cliInvocation()} runner register --agent claude-code\n`
+        `Local runner: not paired\n  Start it: ${cliInvocation()} runner start --background\n`
       );
       return { state: "unpaired" };
     }

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/dist/server.js

@@ -3,10 +3,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { registerUserAuthFlowTools } from "./user_auth_flow.js";
 import { shareAuthFlowToUi } from "./auth_flow_ui.js";
+import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { MCP_PREVIEW_RESOURCE_URI, RESOURCE_URI_META_KEY, buildConversionPanelHtml, writeMcpPreviewFile, } from "./mcp-preview-panel.js";
 let REPO_CONFIG = null;
@@ -1444,11 +1446,34 @@ export function createServer() {
     return server;
 }
 // ── Start ─────────────────────────────────────────────────────────────
+/**
+ * A pre-push hook PreMan wrote can stop working — the machine gained a `preman`
+ * belonging to another package, or lost the one it pinned — and the only symptom
+ * is one skipped line per push. This process starting is proof PreMan runs here,
+ * so it is a good moment to check. Detached with stdio ignored: the check shells
+ * out to npm, and this process's stdout is the MCP protocol.
+ */
+function repairPushHookInBackground() {
+    try {
+        const cli = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "bin", "cli.js");
+        if (!existsSync(cli))
+            return;
+        const child = spawn(process.execPath, [cli, "hook", "repair", "--if-stale"], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+    }
+    catch {
+        // Never worth failing a server start over.
+    }
+}
 async function main() {
     await initAuth();
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    repairPushHookInBackground();
     // Starting the configured MCP server is itself proof that the coding agent
     // is live.  Previously the workbench remained in `connecting` until someone
     // explicitly asked the agent to call `preman_status`, even when this process

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "open-mcp-preview-in-cursor": "node scripts/open-cursor-preview.mjs",
     "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-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"
+    "test:node": "node --test --test-timeout=90000 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 scripts/smoke-api-tools.mjs scripts/smoke-bin-scope.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^0.1.0",