premanmcp 0.10.1 → 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:
 

package/bin/connect.js

@@ -509,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;
@@ -525,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 {
@@ -533,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 ───────────────────────────────────────────────────────
 
 /**
@@ -544,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}`] };
@@ -553,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.
@@ -577,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` };
@@ -592,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;
@@ -618,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) {
@@ -1523,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");
@@ -1546,61 +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}` : ""})`
     );
+
+    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 blocker = agentBlocker(agent.id);
+  let launch = {};
   if (!args.has("--no-auto-checkin") && !blocker) {
-    const spec = headlessCheckIn(agent, serverName);
-    if (spec && onPath(spec.bin)) {
-      process.stdout.write(`\nStarting ${agent.label} to finish the link…\n`);
-    }
-    const auto = await autoCheckIn(args, agent, apiKey, { serverName });
-    if (auto.connected) {
-      for (const note of notes) process.stdout.write(`Note: ${note}\n`);
+    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.
-    process.stdout.write(`${MARK.skip()} ${blocker}\n`);
+    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/runner.js

@@ -612,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.
  *
@@ -633,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 {
@@ -842,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "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-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",