premanmcp 0.8.0 → 0.9.0

package/README.md

@@ -19,11 +19,12 @@ Local development form:
 node bin/cli.js connect
 ```
 
-First-time users are prompted for email, OTP, and password directly in the terminal.
-PreMan creates or connects the account, generates an API key, saves it to
-`~/.preman/credentials.json`, then writes a `preman` MCP server into the config your
-agent actually reads (`~/.cursor/mcp.json`, Claude Code's MCP config, or
-`~/.codex/config.toml`):
+First-time users are asked for an email and the code sent to it — no password: the
+terminal's credential is the `pm_live_` key. Pass `--password` to also set one for
+dashboard sign-in, or set it later from the dashboard. PreMan creates or connects the
+account, generates an API key, saves it to `~/.preman/credentials.json`, then writes a
+`preman` MCP server into the config your agent actually reads (`~/.cursor/mcp.json`,
+Claude Code's MCP config, or `~/.codex/config.toml`):
 
 ```json
 {
@@ -40,11 +41,12 @@ agent actually reads (`~/.cursor/mcp.json`, Claude Code's MCP config, or
 }
 ```
 
-Restart your agent afterwards, then ask it to `run preman_status` to finish linking.
-
 `connect` reads the config back after writing it, and prints a copy-paste snippet if it
-cannot confirm the entry landed. It then waits for your agent to check in — that
-check-in is the only real proof the agent loaded the server.
+cannot confirm the entry landed. It then finishes the link itself by running your agent
+headlessly (`claude -p`, `cursor-agent -p`, `codex exec`) so it makes one PreMan call —
+that check-in is the only real proof the agent loaded the server. If the agent's CLI is
+not on PATH, `connect` asks you to restart it and waits instead. `--no-auto-checkin`
+turns the spawn off.
 
 Once the agent has checked in, `connect` walks you into your first test: it runs one
 against an endpoint you already have, or prints the discovery brief to hand your agent,
@@ -62,10 +64,18 @@ setup blocks for all three agents and exits 2.
 
 ### Cloud dispatch (optional)
 
-`connect` offers to store a coding-agent credential — a Cursor API key, or a Claude
-Code routine token and id. With one saved, PreMan can start an agent run for you when
-it finds a failing endpoint instead of handing back a prompt to paste. Press Enter to
-skip; everything else still works.
+With a coding-agent credential saved — a Cursor API key from
+`cursor.com/dashboard → Integrations → API Keys`, or a Claude Code routine token and id
+from `claude.ai/code/routines → your routine → Add API trigger` — PreMan can start an
+agent run for you when it finds a failing endpoint, instead of handing back a prompt to
+paste.
+
+`connect` asks for it once you are already set up, so skipping costs nothing. Come back
+to it any time:
+
+```bash
+npm exec -y premanmcp@latest -- dispatch
+```
 
 You can also create or connect your account first:
 

package/bin/account.js

@@ -8,7 +8,6 @@
  */
 
 import { existsSync, rmSync } from "node:fs";
-import { spawn } from "node:child_process";
 import os from "node:os";
 
 import { detectCandidates } from "./detect.js";
@@ -19,6 +18,7 @@ import {
   cliInvocation,
   frontendUrl,
   makeArgs,
+  openUrl,
   readStoredCredentials,
   resolveApiKey,
   saveStoredCredentials,
@@ -35,17 +35,6 @@ Account options:
 const POLL_INTERVAL_MS = 3000;
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 
-function openBrowser(url) {
-  const opener =
-    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  try {
-    spawn(opener, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 export async function loginBrowser(args) {
@@ -61,7 +50,7 @@ export async function loginBrowser(args) {
     `\nApprove this device in your browser:\n  ${verificationUrl}\n\n` +
       `Confirmation code: ${start.user_code}\n\n`
   );
-  if (!openBrowser(verificationUrl)) {
+  if (!openUrl(verificationUrl)) {
     process.stdout.write("Could not open a browser automatically — open the link above.\n");
   }
   process.stdout.write("Waiting for approval…\n");

package/bin/cli.js

@@ -17,7 +17,13 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { ENDPOINTS_HELP, TEST_HELP, endpointsCommand, testCommand } from "./api_tools.js";
-import { CONNECT_HELP, connectCommand, writeCursorConfig } from "./connect.js";
+import {
+  CONNECT_HELP,
+  DISPATCH_HELP,
+  connectCommand,
+  dispatchCommand,
+  writeCursorConfig,
+} from "./connect.js";
 import {
   INTEGRATIONS_HELP,
   awsCommand,
@@ -78,6 +84,7 @@ function printHelp() {
     ["install-desktop", "Download and install the PreMan desktop app"],
     ["onboard", "Sign in, then connect agent, 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"],
     ["login [--browser]", "Create/login to PreMan from the terminal"],
     ["logout", "Delete stored CLI credentials"],
@@ -97,7 +104,7 @@ function printHelp() {
 
 Usage:
 ${usageLines}
-${INTEGRATIONS_HELP}${CONNECT_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${ENDPOINTS_HELP}${TEST_HELP}
+${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${ENDPOINTS_HELP}${TEST_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
@@ -224,6 +231,8 @@ async function main() {
     await installDesktopCommand(commandArgs);
   } else if (command === "connect") {
     await connectCommand(commandArgs);
+  } else if (command === "dispatch") {
+    await dispatchCommand(commandArgs);
   } 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.

package/bin/connect.js

@@ -10,7 +10,7 @@
  * never fails the connect.
  */
 
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -53,7 +53,11 @@ const AGENTS = [
     id: "cursor",
     label: "Cursor",
     aliases: ["cursor"],
-    dispatch: { credential: "Cursor API key", needsRoutine: false },
+    dispatch: {
+      credential: "Cursor API key",
+      needsRoutine: false,
+      source: "cursor.com/dashboard → Integrations → API Keys",
+    },
     snippetHint: "merge into ~/.cursor/mcp.json",
     restartHint: 'Fully quit and reopen Cursor, then Settings → MCP → toggle "preman" off and on.',
   },
@@ -61,7 +65,13 @@ const AGENTS = [
     id: "claude_code",
     label: "Claude Code",
     aliases: ["claude", "claude-code", "claude_code", "claudecode"],
-    dispatch: { credential: "Claude Code routine token", needsRoutine: true },
+    dispatch: {
+      credential: "Claude Code routine token",
+      needsRoutine: true,
+      // Named explicitly because "Claude Code routine token" reads like an
+      // Anthropic API key, which is a different credential from a different page.
+      source: "claude.ai/code/routines → your routine → Add API trigger",
+    },
     snippetHint: "run:",
     restartHint: 'Start a new Claude Code session and run `claude mcp list` — "preman" should be listed.',
   },
@@ -97,17 +107,36 @@ function detectAgents() {
   };
 }
 
-async function promptAgentChoice(detected) {
+/**
+ * The agent whose session this command is running inside, if any.
+ *
+ * A better default than "first one installed": someone who types this into an
+ * agent's terminal almost always means that agent, and on a machine with all
+ * three installed the detected-order default is usually wrong.
+ */
+export function runningInside(env = process.env) {
+  if (env.CLAUDECODE || env.CLAUDE_CODE) return "claude_code";
+  if (env.CURSOR_TRACE_ID) return "cursor";
+  return "";
+}
+
+async function promptAgentChoice(detected, insideId = runningInside()) {
   process.stdout.write("Which coding agent?\n");
   AGENTS.forEach((agent, index) => {
-    const mark = detected[agent.id] ? "  (detected)" : "";
+    let mark = "";
+    if (agent.id === insideId) mark = "  (this session)";
+    else if (detected[agent.id]) mark = "  (detected)";
     process.stdout.write(`  ${index + 1}. ${agent.label}${mark}\n`);
   });
 
-  const defaultIndex = Math.max(
-    0,
-    AGENTS.findIndex((a) => detected[a.id])
-  );
+  const inside = AGENTS.findIndex((a) => a.id === insideId);
+  const defaultIndex =
+    inside >= 0
+      ? inside
+      : Math.max(
+          0,
+          AGENTS.findIndex((a) => detected[a.id])
+        );
   const answer = await promptText(`Pick [${defaultIndex + 1}]: `);
   if (!answer) return AGENTS[defaultIndex];
 
@@ -381,6 +410,7 @@ export async function waitForConnection(
   {
     intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
     timeoutMs = Number(process.env.PREMAN_CONNECT_WAIT_MS) || 300000,
+    stopWhen = null,
   } = {}
 ) {
   const deadline = Date.now() + timeoutMs;
@@ -396,6 +426,7 @@ export async function waitForConnection(
         token: apiKey,
       });
       if (status.ok && status.connected) return true;
+      if (stopWhen && stopWhen()) return false;
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
   } finally {
@@ -404,9 +435,94 @@ export async function waitForConnection(
   return false;
 }
 
+// ── Auto check-in ───────────────────────────────────────────────────────
+
+/**
+ * How to ask each agent to make one PreMan call without opening its UI.
+ *
+ * The link is established by the agent's first call, so anything that reaches
+ * `preman_status` finishes the connect. Claude Code needs the server on its
+ * allow-list because print mode refuses un-allowed MCP tools rather than
+ * prompting.
+ */
+export function headlessCheckIn(agent, serverName) {
+  const prompt = `Call the ${serverName} MCP tool preman_status and report the result.`;
+  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}`] };
+  }
+  if (agent.id === "codex") return { bin: "codex", args: ["exec", prompt] };
+  return null;
+}
+
+/**
+ * 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.
+ *
+ * Returns `ran: false` when the agent's binary is absent or will not start, and
+ * the caller falls back to the printed instructions.
+ */
+export async function autoCheckIn(
+  args,
+  agent,
+  apiKey,
+  {
+    // Never outlast the connect's own wait budget: this phase is part of it, not
+    // an extra one bolted on the front.
+    timeoutMs = Math.min(
+      Number(process.env.PREMAN_AUTO_CHECKIN_MS) || 120000,
+      Number(process.env.PREMAN_CONNECT_WAIT_MS) || 300000
+    ),
+    serverName = "preman",
+    intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
+  } = {}
+) {
+  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` };
+
+  let child;
+  try {
+    child = spawn(spec.bin, spec.args, { stdio: "ignore" });
+  } catch (error) {
+    return { ran: false, connected: false, reason: error.message };
+  }
+
+  let spawnError = null;
+  let exitedAt = 0;
+  child.on("error", (error) => {
+    spawnError = error;
+    exitedAt = exitedAt || Date.now();
+  });
+  child.on("exit", () => {
+    exitedAt = exitedAt || Date.now();
+  });
+
+  // The check-in can land moments after the agent's own process ends, so keep
+  // polling briefly past its exit rather than declaring failure at the edge.
+  const grace = intervalMs * 2;
+  try {
+    const connected = await waitForConnection(args, apiKey, {
+      intervalMs,
+      timeoutMs,
+      stopWhen: () => Boolean(exitedAt) && Date.now() - exitedAt > grace,
+    });
+    if (spawnError && !connected) {
+      return { ran: false, connected: false, reason: spawnError.message };
+    }
+    return { ran: true, connected, command: spec.bin };
+  } finally {
+    if (child.exitCode === null && child.signalCode === null) child.kill();
+  }
+}
+
 // ── Dispatch credential (SCRUM-124) ─────────────────────────────────────
 
-async function captureDispatchCredential(args, agent, apiKey) {
+async function captureDispatchCredential(args, agent, apiKey, { prompt = true } = {}) {
   if (!agent.dispatch) return;
   if (args.has("--skip-dispatch-credential")) return;
 
@@ -414,19 +530,20 @@ async function captureDispatchCredential(args, agent, apiKey) {
   let routineId = args.value("--routine-id", "");
 
   if (!secret) {
-    if (!process.stdin.isTTY) return;
+    if (!prompt || !process.stdin.isTTY) return;
     // Framed as the expected step rather than an optional aside. Without it
     // PreMan can only suggest fixes; with it, it can run them. Presenting it as
     // "optional, press Enter to skip" meant almost everyone skipped the thing
     // that makes the product act rather than advise.
     process.stdout.write(
-      `\nLet PreMan start ${agent.label} runs for you — it can then apply fixes and\n` +
-        `run checks on a schedule instead of only telling you what to do.\n`
+      `\nOptional — let PreMan start ${agent.label} runs for you, so it can apply\n` +
+        `fixes and run checks on a schedule instead of only telling you what to do.\n` +
+        `Get the token from ${agent.dispatch.source}.\n`
     );
-    secret = await promptSecret(`Paste your ${agent.dispatch.credential} (Enter to set up later): `);
+    secret = await promptSecret(`Paste your ${agent.dispatch.credential} (Enter to skip): `);
     if (!secret) {
       process.stdout.write(
-        `Skipped. Run '${cliInvocation()} connect --agent ${agent.id.replace("_", "-")}' when you have the token.\n`
+        `Skipped. Run '${cliInvocation()} dispatch --agent ${agent.id.replace("_", "-")}' when you have the token.\n`
       );
       return;
     }
@@ -458,6 +575,64 @@ async function captureDispatchCredential(args, agent, apiKey) {
   }
 }
 
+export const DISPATCH_HELP = `
+Dispatch options:
+  --agent <name>              cursor | claude-code (defaults to the connected agent)
+  --dispatch-credential <t>   Cloud-dispatch token (non-interactive)
+  --routine-id <id>           Claude Code routine id, with --dispatch-credential
+  --api-key <key>             PreMan API key. If omitted, stored credentials are used
+  --backend <url>             PreMan backend URL
+`;
+
+/**
+ * `preman dispatch` — store the cloud-dispatch credential on its own.
+ *
+ * Exists so connect never has to ask for a token mid-onboarding. Someone who
+ * skipped it (or did not have it yet) comes back here instead of re-running the
+ * whole connect.
+ */
+export async function dispatchCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const apiKey = resolveApiKey(args);
+  if (!apiKey) {
+    throw new ConnectError(
+      `No PreMan credentials. Run '${cliInvocation()} connect' first, or pass --api-key pm_live_….`,
+      EXIT_USAGE
+    );
+  }
+
+  let agent = findAgent(args.value("--agent", ""));
+  if (!agent && args.value("--agent", "")) {
+    throw new ConnectError(
+      `Unknown agent: ${args.value("--agent", "")}. Use cursor or claude-code.`,
+      EXIT_USAGE
+    );
+  }
+
+  if (!agent) {
+    const current = await callBackendJson(args, "GET", "/workbench/coding-agent", { token: apiKey });
+    agent = findAgent(current.ok ? current.agent : "");
+    if (!agent) {
+      throw new ConnectError(
+        "Could not tell which agent to set up. Pass --agent cursor or --agent claude-code.",
+        EXIT_USAGE
+      );
+    }
+  }
+
+  if (!agent.dispatch) {
+    throw new ConnectError(`${agent.label} has no cloud-dispatch API yet.`, EXIT_USAGE);
+  }
+  if (!args.value("--dispatch-credential", "") && !process.stdin.isTTY) {
+    throw new ConnectError(
+      "preman dispatch needs a terminal, or --dispatch-credential <token>.",
+      EXIT_USAGE
+    );
+  }
+
+  await captureDispatchCredential(args, agent, apiKey);
+}
+
 /** Accept either a bare trig_… id or the routine URL it appears in. */
 export function extractRoutineId(value) {
   const raw = String(value || "").trim();
@@ -602,6 +777,7 @@ Connect options:
   --project                   Write project-local config instead of the user config
   --api-key <key>             PreMan API key. If omitted, stored credentials are used
   --email <email>             Pre-fill the email prompt when logging in
+  --password [value]          Also set a dashboard password (signup asks for none)
   --backend <url>             PreMan backend URL
   --frontend <url>            PreMan frontend URL
   --name <name>               MCP server name. Defaults to preman
@@ -610,6 +786,7 @@ Connect options:
   --skip-dispatch-credential  Do not ask for a cloud-dispatch credential
   --skip-login                Write config without interactive terminal auth
   --no-pair                   Do not mint a pair code
+  --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
   --print                     Print the config instead of writing it
@@ -630,31 +807,23 @@ export async function connectCommand(commandArgs) {
     );
   }
 
-  if (!agent) {
-    if (!interactive) {
-      // Nothing to prompt on, so leave behind everything a CI log needs to
-      // finish the setup by hand rather than just the reason it stopped.
-      process.stdout.write(
-        `preman connect needs a terminal to pick an agent. Copy-paste setup instead:\n\n${renderAllAgentSnippets(args, serverName, { projectInstall })}\n` +
-          'Then restart your agent and ask it: "run preman_status".\n' +
-          "Or rerun: preman connect --agent <cursor|claude-code|codex> --api-key pm_live_…\n"
-      );
-      throw new ConnectError(
-        "preman connect needs a terminal. In CI pass --agent <cursor|claude-code|codex> " +
-          "and --api-key pm_live_… (or --print), or use one of the snippets above.",
-        EXIT_USAGE
-      );
-    }
-    agent = await promptAgentChoice(detectAgents());
-  }
-
-  if (!printOnly) {
-    // Verify the machine can run what we are about to write — before any
-    // config edits or logins, so failures leave nothing half-done.
-    await preflight(args);
+  // Nothing to prompt on, so leave behind everything a CI log needs to finish
+  // the setup by hand rather than just the reason it stopped.
+  if (!agent && !interactive) {
+    process.stdout.write(
+      `preman connect needs a terminal to pick an agent. Copy-paste setup instead:\n\n${renderAllAgentSnippets(args, serverName, { projectInstall })}\n` +
+        'Then restart your agent and ask it: "run preman_status".\n' +
+        "Or rerun: preman connect --agent <cursor|claude-code|codex> --api-key pm_live_…\n"
+    );
+    throw new ConnectError(
+      "preman connect needs a terminal. In CI pass --agent <cursor|claude-code|codex> " +
+        "and --api-key pm_live_… (or --print), or use one of the snippets above.",
+      EXIT_USAGE
+    );
   }
 
   if (printOnly) {
+    if (!agent) agent = await promptAgentChoice(detectAgents());
     const serverConfig = buildServerConfig(args);
     if (agent.id === "codex") {
       process.stdout.write(renderCodexToml(serverName, serverConfig));
@@ -664,6 +833,12 @@ export async function connectCommand(commandArgs) {
     return;
   }
 
+  // Verify the machine can run what we are about to write — before any config
+  // edits or logins, so failures leave nothing half-done.
+  await preflight(args);
+
+  // Account first, so "First, let's connect your PreMan account" is not the
+  // second thing that happens.
   if (!args.has("--skip-login") && !hasKeyAvailable(args)) {
     if (!interactive) {
       throw new ConnectError(
@@ -676,6 +851,8 @@ export async function connectCommand(commandArgs) {
     process.stdout.write("\n");
   }
 
+  if (!agent) agent = await promptAgentChoice(detectAgents());
+
   const apiKey = resolveApiKey(args);
 
   let pairCode = "";
@@ -708,27 +885,19 @@ export async function connectCommand(commandArgs) {
     );
   }
 
-  // Not gated on TTY: --dispatch-credential is the non-interactive path, and the
-  // prompt inside only runs when there is a terminal to prompt on.
-  await captureDispatchCredential(args, agent, apiKey);
-
+  // A non-interactive run can still be handed the credential up front, so this
+  // stays reachable; the prompt inside only fires when there is a TTY, and by
+  // then onboarding is done.
   if (!pairCode || args.has("--no-wait") || !interactive) {
+    await captureDispatchCredential(args, agent, apiKey);
     process.stdout.write(nextStepsBlock(agent));
     return;
   }
 
-  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"
-  );
-
-  if (!(await waitForConnection(args, apiKey))) {
-    process.stdout.write(
-      "No check-in yet. Troubleshooting:\n" +
-        `  - ${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`
-    );
+  if (!(await establishCheckIn(args, agent, apiKey, { serverName, written }))) {
+    // 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;
   }
 
@@ -736,4 +905,42 @@ export async function connectCommand(commandArgs) {
   if (!args.has("--no-guide")) {
     await guidedFirstRun(args, agent);
   }
+  await captureDispatchCredential(args, agent, apiKey);
+}
+
+/**
+ * Get the agent to make its first PreMan call, by whatever means work here.
+ *
+ * Prefers running it for the user; falls back to asking them to restart it and
+ * waiting, which is all this ever did. Returns whether the check-in landed, and
+ * prints the troubleshooting block itself when it did not.
+ */
+async function establishCheckIn(args, agent, apiKey, { serverName, written }) {
+  if (!args.has("--no-auto-checkin")) {
+    const spec = headlessCheckIn(agent, serverName);
+    if (spec && onPath(spec.bin)) {
+      process.stdout.write(`\nStarting ${agent.label} to finish the link…\n`);
+    }
+    const auto = await autoCheckIn(args, agent, apiKey, { serverName });
+    if (auto.connected) return true;
+    if (auto.ran) {
+      process.stdout.write(`${agent.label} ran but did not check in.\n`);
+    }
+  }
+
+  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"
+  );
+
+  if (await waitForConnection(args, apiKey)) return true;
+
+  process.stdout.write(
+    "No check-in yet. Troubleshooting:\n" +
+      `  - ${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` +
+      `  - Then: ${cliInvocation()} connect --agent ${agent.id.replace("_", "-")}\n`
+  );
+  return false;
 }

package/bin/integrations.js

@@ -14,12 +14,11 @@
  * hand, and no third-party credential ever touches the terminal.
  */
 
-import { spawn } from "node:child_process";
-
 import {
   assertOk,
   callBackendJson,
   frontendUrl,
+  openUrl,
   promptText,
   resolveApiKey,
 } from "./shared.js";
@@ -42,9 +41,9 @@ function paint(code, text) {
 }
 
 export const MARK = {
-  ok: () => paint("32", "✓"),
-  skip: () => paint("90", "○"),
-  fail: () => paint("31", "✗"),
+  ok: () => paint("32", "?"),
+  skip: () => paint("90", "?"),
+  fail: () => paint("31", "?"),
 };
 
 /** A finished step, marked so it can be found at a glance. */
@@ -52,25 +51,6 @@ export function connected(message) {
   process.stdout.write(`${MARK.ok()} ${message}\n`);
 }
 
-/** Open a URL in the customer's default browser, best effort. */
-export function openUrl(url) {
-  const command =
-    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  try {
-    const child = spawn(command, [url], {
-      stdio: "ignore",
-      detached: true,
-      shell: process.platform === "win32",
-    });
-    child.unref();
-    return true;
-  } catch {
-    // Headless boxes and locked-down shells are normal. The URL is printed
-    // either way, so this is a convenience, never the only path.
-    return false;
-  }
-}
-
 function present(url, what) {
   process.stdout.write(`\n  ${url}\n\n`);
   if (openUrl(url)) process.stdout.write(`Opened ${what} in your browser.\n`);
@@ -349,7 +329,7 @@ export async function onboardCommand(commandArgs, { makeArgs, authenticateTermin
   let i = 0;
   while (i < steps.length) {
     const step = steps[i];
-    process.stdout.write(`\n── ${step.name} ──\n`);
+    process.stdout.write(`\n?? ${step.name} ??\n`);
 
     const choice = await askStep(step.question, { assumeYes, canGoBack: i > 0 });
     if (choice === "back") {
@@ -377,7 +357,7 @@ export async function onboardCommand(commandArgs, { makeArgs, authenticateTermin
     i += 1;
   }
 
-  process.stdout.write("\n── done ──\n");
+  process.stdout.write("\n?? done ??\n");
   // One line per step, marked, so the outcome is scannable rather than prose.
   for (const step of steps) {
     const result = outcome.get(step.name);

package/bin/shared.js

@@ -7,7 +7,7 @@
  * over a module-level argv, so a command can pass its own slice.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -101,6 +101,36 @@ export function frontendUrl(args) {
   return args.value("--frontend", process.env.PREMAN_FRONTEND || DEFAULT_FRONTEND).replace(/\/+$/, "");
 }
 
+/**
+ * Open a URL in the user's default browser, best effort.
+ *
+ * Returns false without spawning anything when nobody is there to look at it:
+ * `PREMAN_NO_BROWSER` for an explicit no, and a non-TTY stdout for CI, piped
+ * output, and test runs. Every caller prints the URL as well, so this is only
+ * ever a convenience — a suite that exercises these flows should not be able to
+ * throw tabs at whoever is running it.
+ */
+export function openUrl(url) {
+  const optOut = (process.env.PREMAN_NO_BROWSER || "").trim().toLowerCase();
+  if (optOut && !["0", "false", "no"].includes(optOut)) return false;
+  if (!process.stdout.isTTY) return false;
+
+  const opener =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    const child = spawn(opener, [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32",
+    });
+    child.unref();
+    return true;
+  } catch {
+    // Headless boxes and locked-down shells are normal.
+    return false;
+  }
+}
+
 export async function promptText(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
@@ -235,7 +265,50 @@ async function verifyUnconfirmedAccount(args, email) {
   return verified.access_token;
 }
 
+/**
+ * A password only if the caller asked for one.
+ *
+ * The terminal's durable credential is the pm_live_ key, so signup does not
+ * need a password and no longer asks for one. `--password` is for anyone who
+ * wants to be able to sign in to the dashboard immediately; `--password <value>`
+ * skips the prompt for scripted runs.
+ */
+async function optionalPassword(args) {
+  if (!args.has("--password")) return "";
+  const supplied = args.value("--password", "");
+  // Bare `--password` followed by another flag means "prompt me", not "my
+  // password is --backend".
+  if (supplied && !supplied.startsWith("--")) {
+    if (supplied.length < 6) throw new Error("Password must be at least 6 characters.");
+    return supplied;
+  }
+  return promptPasswordTwice();
+}
+
+/**
+ * Turn a verification code into a session token.
+ *
+ * Without a password this is one call: verify-otp signs the user in and the
+ * backend keeps the account passwordless, so the dashboard knows to offer a
+ * code rather than a password field.
+ */
+async function completeWithCode(args, email, otp, password) {
+  if (password) {
+    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    return String(setPassword.access_token || "");
+  }
+  const verified = await callBackendJson(args, "POST", "/auth/verify-otp", {
+    json: { email, otp },
+  });
+  assertOk(verified, "verify OTP");
+  return String(verified.access_token || "");
+}
+
 async function createAccountFromTerminal(args, email) {
+  const password = await optionalPassword(args);
   const signup = await callBackendJson(args, "POST", "/auth/start-signup", {
     json: { email },
   });
@@ -243,24 +316,21 @@ async function createAccountFromTerminal(args, email) {
   if (signup.ok) {
     process.stdout.write("Verification code sent. Check your email.\n");
     const otp = await promptText("Verification code: ");
-    const password = await promptPasswordTwice();
-    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
-      json: { email, otp, new_password: password },
-    });
-    assertOk(setPassword, "set password");
-    return String(setPassword.access_token || "");
+    return completeWithCode(args, email, otp, password);
   }
 
   if (signup.status_code !== 404) {
     assertOk(signup, "start signup");
   }
 
+  // Backends predating start-signup have no passwordless route in, so this one
+  // path still has to ask.
   process.stdout.write(
     "This PreMan backend uses the password-first signup flow. Create your password now, then enter the email code.\n"
   );
-  const password = await promptPasswordTwice();
+  const legacyPassword = password || (await promptPasswordTwice());
   const legacySignup = await callBackendJson(args, "POST", "/auth/signup", {
-    json: { email, password },
+    json: { email, password: legacyPassword },
   });
   assertOk(legacySignup, "signup");
   process.stdout.write("Verification code sent. Check your email.\n");
@@ -303,26 +373,31 @@ export async function authenticateTerminal(args) {
     process.stdout.write("No PreMan account found. Creating one now.\n");
     accessToken = await createAccountFromTerminal(args, email);
   } else if (account.needs_password) {
-    process.stdout.write("This account needs a password. Sending an OTP first.\n");
+    // No password on this account, so a code is the only way in.
+    const password = await optionalPassword(args);
+    process.stdout.write("Sending a sign-in code to your email.\n");
     const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
     assertOk(resend, "resend OTP");
     const otp = await promptText("Verification code: ");
-    const password = await promptPasswordTwice();
-    const setPassword = await callBackendJson(args, "POST", "/auth/set-password", {
-      json: { email, otp, new_password: password },
-    });
-    assertOk(setPassword, "set password");
-    accessToken = String(setPassword.access_token || "");
+    accessToken = await completeWithCode(args, email, otp, password);
   } else {
-    const password = await promptSecret("Password: ");
-    const login = await callBackendJson(args, "POST", "/auth/login", {
-      json: { email, password },
-    });
-    if (!login.ok && login.status_code === 403 && String(login.detail || "").toLowerCase().includes("not verified")) {
-      accessToken = await verifyUnconfirmedAccount(args, email);
+    const password = await promptSecret("Password (Enter to get a code by email): ");
+    if (!password) {
+      const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
+      assertOk(resend, "resend OTP");
+      process.stdout.write("Sign-in code sent. Check your email.\n");
+      const otp = await promptText("Verification code: ");
+      accessToken = await completeWithCode(args, email, otp, "");
     } else {
-      assertOk(login, "login");
-      accessToken = String(login.access_token || "");
+      const login = await callBackendJson(args, "POST", "/auth/login", {
+        json: { email, password },
+      });
+      if (!login.ok && login.status_code === 403 && String(login.detail || "").toLowerCase().includes("not verified")) {
+        accessToken = await verifyUnconfirmedAccount(args, email);
+      } else {
+        assertOk(login, "login");
+        accessToken = String(login.access_token || "");
+      }
     }
   }
 

package/package.json

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