premanmcp 0.10.2 → 0.10.3

package/README.md

@@ -58,9 +58,11 @@ to go restart anything, in cheapest-first order:
 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. 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.
+that file overrides `PREMAN_BACKEND`, the config `connect` wrote is still correct: the
+server reads that file only from the directory it starts in, so `connect` names the file
+and then retries from your home directory, where the override cannot reach it — self-test
+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:
 

package/bin/connect.js

@@ -690,6 +690,11 @@ export function openInNewTerminal(command, options = {}) {
  * machine with no terminal emulator — does this fall back to the headless run,
  * which still finishes the link even though nobody sees it happen.
  *
+ * `cwd` is where the agent starts, and it is load-bearing rather than tidiness:
+ * the MCP server reads its repo config out of the working directory, so starting
+ * the agent elsewhere is how a caller escapes a directory that would otherwise
+ * redirect it to a backend this key was never issued for.
+ *
  * Returns `ran: false` when the agent's binary is absent or will not start, and
  * the caller falls back to the printed instructions.
  */
@@ -706,13 +711,14 @@ export async function autoCheckIn(
     ),
     serverName = "preman",
     intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
+    cwd = process.cwd(),
     onLaunch = () => {},
     onPoll = null,
   } = {}
 ) {
   const session = interactiveCheckIn(agent, serverName);
   if (session && onPath(session.bin)) {
-    const { opened, terminal } = openInNewTerminal(commandLine(session), { cwd: process.cwd() });
+    const { opened, terminal } = openInNewTerminal(commandLine(session), { 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
@@ -732,7 +738,7 @@ export async function autoCheckIn(
     // Piped rather than ignored: an agent that runs and does not check in used to
     // report exactly that and nothing else, which is the least useful sentence
     // available. Its own last words usually name the cause.
-    child = spawn(spec.bin, spec.args, { stdio: ["ignore", "pipe", "pipe"] });
+    child = spawn(spec.bin, spec.args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
   } catch (error) {
     return { ran: false, connected: false, reason: error.message };
   }
@@ -1655,7 +1661,14 @@ export async function connectCommand(commandArgs) {
     return;
   }
 
-  if (!(await establishCheckIn(args, agent, apiKey, { serverName, written, serverConfig }))) {
+  if (
+    !(await establishCheckIn(args, agent, apiKey, {
+      serverName,
+      written,
+      serverConfig,
+      projectInstall,
+    }))
+  ) {
     // 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 });
@@ -1687,6 +1700,30 @@ function backendRedirect(repo, status, serverConfig) {
   return { path: repo.path, actual, wanted };
 }
 
+/**
+ * Somewhere to start the agent when this directory would redirect its backend.
+ *
+ * The server reads its repo config from the working directory and nowhere else —
+ * no walk up to the parents — so any directory without one of those two files is
+ * already out of the override's reach. Home first, because an agent started there
+ * is in a place the user recognises; a temp dir only if home is itself a repo
+ * carrying a config.
+ *
+ * Null means every candidate was covered, and the caller has nothing to offer but
+ * the instructions.
+ */
+export function neutralCwd(candidates = [os.homedir(), os.tmpdir()]) {
+  return (
+    candidates.find(
+      (dir) =>
+        dir &&
+        existsSync(dir) &&
+        !existsSync(path.join(dir, ".cursor", "preman-mcp.config.json")) &&
+        !existsSync(path.join(dir, "preman-mcp.config.json"))
+    ) || null
+  );
+}
+
 /**
  * Finish the link here, by whatever means work, in cheapest-first order.
  *
@@ -1697,6 +1734,12 @@ function backendRedirect(repo, status, serverConfig) {
  *    the config we wrote.
  * 3. Failing that, ask them to restart it and wait, which is all this ever did.
  *
+ * A directory whose repo config redirects the backend moves steps 1 and 2 out of
+ * that directory rather than giving up in it: the config on disk is right, and
+ * where the server and the agent stand is the only thing that has to change. Not
+ * step 2 under `--project`, though — that config exists in that directory alone,
+ * so an agent sent anywhere else would have no server to call.
+ *
  * 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.
@@ -1704,8 +1747,16 @@ function backendRedirect(repo, status, serverConfig) {
  * 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 }) {
+async function establishCheckIn(
+  args,
+  agent,
+  apiKey,
+  { 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.
+  let elsewhere = null;
   const ticker = pollTicker();
   const say = (text) => {
     ticker.end();
@@ -1741,15 +1792,62 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written, serv
     const redirect = backendRedirect(repo, status, serverConfig);
     if (redirect) {
       const flag = `--agent ${agent.id.replace("_", "-")}`;
+      const notLinked = (why) =>
+        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` +
+            `  - ${why}\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`
+        );
+      notes.push(
+        `start ${agent.label} from another project, or connect to the backend this ` +
+          `directory forces: ${cliInvocation()} connect ${flag} --backend ${redirect.actual} ` +
+          `(needs a key issued by it, and that API running).`
+      );
+
+      // 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
+      // happens somewhere the override cannot reach.
+      const outside = neutralCwd();
+      if (!outside) {
+        notLinked(`Run '${cliInvocation()} connect' from your own project instead of this directory.`);
+        return false;
+      }
+
       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`
+        (projectInstall
+          ? `\nThe key and backend written are right: ${redirect.path}\n` +
+            `only redirects what starts in this directory. `
+          : `\nThe config is written and works anywhere else: ${redirect.path}\n` +
+            `only redirects agents started in this directory. `) +
+          `Trying again from\n${outside}, which is out of that file's reach.\n`
       );
-      return false;
+      // Nothing was wrong with the self-test but where it stood, and a self-test
+      // is what completes the link — so re-run it before spending an agent window
+      // on the same question. This works under --project too: it runs the config
+      // in memory rather than loading it from disk.
+      const retry = await mcpSelfTest(serverConfig, { cwd: outside });
+      if (
+        retry.ok &&
+        retry.status?.authenticated &&
+        (await waitForConnection(args, apiKey, { timeoutMs: 15000 }))
+      ) {
+        return true;
+      }
+
+      if (projectInstall) {
+        // --project put the server in this directory and nowhere else, so there
+        // is no config to load anywhere the override cannot reach, and no agent
+        // worth starting to look for one.
+        notLinked(
+          `This --project config exists only here; started anywhere else, ` +
+            `${agent.label} has no ${serverName} server to call.`
+        );
+        return false;
+      }
+      elsewhere = outside;
     }
   }
 
@@ -1758,6 +1856,7 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written, serv
   if (!args.has("--no-auto-checkin") && !blocker) {
     launch = await autoCheckIn(args, agent, apiKey, {
       serverName,
+      cwd: elsewhere || process.cwd(),
       onPoll: ticker.tick,
       onLaunch: ({ mode, terminal }) =>
         say(
@@ -1787,7 +1886,11 @@ async function establishCheckIn(args, agent, apiKey, { serverName, written, serv
     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` +
+      : // Restarting it here would read the same redirecting file again, so the
+        // one instruction that works is to start it somewhere else.
+        (elsewhere
+          ? `\nStart ${agent.label} in another project and ask it: "run preman_status"\n`
+          : `\nRestart ${agent.label} and ask it: "run preman_status"\n`) +
           "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
   );
 

package/package.json

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