premanmcp 0.13.0 → 0.15.0

package/bin/repo.js

@@ -0,0 +1,193 @@
+/**
+ * Which repository is this checkout, and does PreMan already know it?
+ *
+ * The CLI has always known it was inside *a* git repository — `preman hook
+ * install` asks git for the git-dir, and agent pairing sends `process.cwd()` —
+ * but never which GitHub repository that was. So a terminal-first user finished
+ * setup with no way to learn whether the code under their cwd was connected,
+ * and the answer only surfaced much later as a fix task that produced no pull
+ * request because its endpoint came from outside a connected repo.
+ *
+ * Reading the remote is a hint, never an action. Nothing here connects a
+ * repository, grants access, or writes to the account: it turns "go and connect
+ * a repo" into "connect acme/api?", and stops there.
+ */
+
+import { spawnSync } from "node:child_process";
+
+import { callBackendJson } from "./shared.js";
+
+// Local git calls answer in milliseconds. The timeout exists for the pathological
+// case — a network filesystem, a repository mid-rebase — where blocking setup on
+// git is worse than not knowing which repo this is.
+const GIT_TIMEOUT_MS = 3000;
+
+/** Owner and repo names GitHub itself accepts. */
+const NAME = /^[A-Za-z0-9._-]+$/;
+
+function git(...gitArgs) {
+  try {
+    const result = spawnSync("git", gitArgs, {
+      encoding: "utf8",
+      timeout: GIT_TIMEOUT_MS,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return result.status === 0 ? String(result.stdout || "").trim() : "";
+  } catch {
+    // No git on PATH is not this command's problem to report.
+    return "";
+  }
+}
+
+/**
+ * The remote this checkout pushes to, or "".
+ *
+ * `origin` first because it is what the overwhelming majority of clones call
+ * their upstream. A single differently-named remote is still unambiguous, so it
+ * counts; two of them are a choice we have no business guessing at, since
+ * picking the wrong one would name someone else's repository.
+ */
+export function checkoutRemote() {
+  const origin = git("remote", "get-url", "origin");
+  if (origin) return origin;
+
+  const named = git("remote").split("\n").map((line) => line.trim()).filter(Boolean);
+  return named.length === 1 ? git("remote", "get-url", named[0]) : "";
+}
+
+/**
+ * Reduce a git remote to `owner/repo`, or "" when it is not GitHub.
+ *
+ * Deliberately not "send the remote and let the backend parse it". A remote can
+ * carry credentials — `https://x-access-token:ghp_…@github.com/acme/api` is what
+ * a CI clone or a credential helper leaves in the config — and while the backend
+ * rejects a URL with userinfo, by then the token has already crossed the network
+ * and can be sitting in a request log. Discarding everything but the two names
+ * locally means there is nothing to leak, and the backend still has final say on
+ * whether the pair is a repository it will accept.
+ */
+export function githubSlug(remote) {
+  let value = String(remote || "").trim();
+  if (!value || value.length > 2000) return "";
+
+  // scp-style: git@github.com:owner/repo.git — not a URL, so it is matched
+  // before anything tries to parse it as one.
+  const scp = /^(?:[^@/]+@)?([^:/]+):(.+)$/.exec(value);
+  if (scp && !value.includes("://")) {
+    if (!isGitHubHost(scp[1])) return "";
+    return pair(scp[2]);
+  }
+
+  if (value.includes("://")) {
+    let parsed;
+    try {
+      parsed = new URL(value);
+    } catch {
+      return "";
+    }
+    // `hostname` excludes any userinfo, so a token in the remote never reaches
+    // the comparison and never reaches the return value.
+    if (!isGitHubHost(parsed.hostname)) return "";
+    return pair(parsed.pathname);
+  }
+
+  // A bare `owner/repo`, or `github.com/owner/repo` pasted without a scheme.
+  for (const prefix of ["github.com/", "www.github.com/"]) {
+    if (value.toLowerCase().startsWith(prefix)) {
+      value = value.slice(prefix.length);
+      break;
+    }
+  }
+  return pair(value);
+}
+
+function isGitHubHost(host) {
+  return ["github.com", "www.github.com"].includes(String(host || "").toLowerCase());
+}
+
+function pair(rawPath) {
+  const parts = String(rawPath || "")
+    .split("/")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (parts.length !== 2) return "";
+
+  const [owner, repoPart] = parts;
+  const repo = repoPart.replace(/\.git$/i, "");
+  if (!NAME.test(owner) || !NAME.test(repo)) return "";
+  if ([owner, repo].some((name) => name === "." || name === "..")) return "";
+  return `${owner}/${repo}`;
+}
+
+/**
+ * Ask the backend which connected repository this checkout is, if any.
+ *
+ * Returns null when there is nothing to ask about — not a repo, no remote, not
+ * GitHub — so callers can treat "no answer" and "not connected" as the different
+ * situations they are. Never throws: this is a courtesy on top of setup, and
+ * setup must not fail because a lookup did.
+ */
+export async function resolveCheckout(args, token, { slug = checkoutRemote() } = {}) {
+  const owner = githubSlug(slug);
+  if (!owner) return null;
+
+  try {
+    const result = await callBackendJson(args, "POST", "/integrations/github/resolve", {
+      token,
+      json: { remote_url: owner },
+    });
+    if (!result.ok) return null;
+    return { slug: owner, ...result };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Why there is no repository to offer, in one sentence, or "" if there is one.
+ *
+ * `resolveCheckout` answering null is four different situations, and the
+ * difference is the whole of what the customer does next: create a repository,
+ * add a remote, name which remote, or accept that PreMan opens pull requests on
+ * GitHub only. Setup used to fall silent on all four, which read as PreMan
+ * having nothing to say about the directory it was standing in — and left the
+ * one thing that decides whether a fix can ever open a PR entirely unmentioned.
+ */
+export function explainNoCheckout() {
+  if (!git("rev-parse", "--git-dir")) {
+    return "Not a git repository, so there is no repository to connect here.";
+  }
+  const remote = checkoutRemote();
+  if (!remote) {
+    return "This checkout has no single remote to read, so there is no repository to connect.";
+  }
+  if (!githubSlug(remote)) {
+    return `${remote} is not a GitHub remote — PreMan opens pull requests on GitHub only.`;
+  }
+  // A slug we could read but the backend would not resolve: its own outage, a
+  // revoked key, a host it does not accept. Worth separating from the three
+  // above because re-running is the fix, and for those three it is not.
+  return `Could not check ${githubSlug(remote)} with PreMan just now.`;
+}
+
+/**
+ * What to tell the user about a resolved checkout, or "" when nothing is worth
+ * saying. Never more than the two lines that change what they do next.
+ */
+export function describeCheckout(resolution) {
+  if (!resolution || resolution.supported === false) return "";
+  const { slug, match, detail } = resolution;
+
+  if (!match) return `${slug} is not connected to PreMan yet.\n`;
+
+  // Connected and able to open PRs: one line, because there is no action left.
+  if (!resolution.blockers?.length) {
+    return `${slug} is connected — fixes here can open a pull request.\n`;
+  }
+
+  // Connected but a fix would stop short of a PR. Worth saying now: the gap is
+  // invisible until a fix task has already been worked, and it is the owner's
+  // toggle to flip.
+  const why = detail || "Auto-PR is not available for this repository yet.";
+  return `${slug} is connected, but fixes here cannot open a pull request:\n  ${why}\n`;
+}

package/bin/shared.js

@@ -222,12 +222,45 @@ export function apiKeyIsExplicit(args) {
   return Boolean(args.value("--api-key", "") || process.env.PREMAN_API_KEY);
 }
 
+/**
+ * The saved login, but only when it is the login actually in play.
+ *
+ * A key given by flag or environment overrides the stored one and may belong to
+ * an entirely different deployment, so the URLs saved beside the stored key must
+ * not be applied to it. Keeping the two together is the whole point: reading the
+ * key out of this file while ignoring the backend recorded next to it is what
+ * sends a local key to production and collects a 401.
+ */
+function activeLogin(args) {
+  return apiKeyIsExplicit(args) ? null : readStoredCredentials();
+}
+
+/**
+ * Which PreMan deployment this invocation talks to.
+ *
+ * The stored fallback is what makes the answer survive a git hook. A hook runs
+ * in whatever environment `git push` had, which is rarely the shell that
+ * exported PREMAN_BACKEND -- and a dev.env file is not an environment, it
+ * belongs to the API server, not to this CLI. Login already writes the backend
+ * down beside the key it minted there; this reads it back.
+ */
 export function backendUrl(args) {
-  return args.value("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND).replace(/\/+$/, "");
+  return args
+    .value("--backend", process.env.PREMAN_BACKEND || activeLogin(args)?.backend_url || DEFAULT_BACKEND)
+    .replace(/\/+$/, "");
 }
 
+/**
+ * Where the dashboard lives for this user.
+ *
+ * Same durability problem as the backend, and the same fix -- with the same
+ * pairing rule, because a run lives on whichever deployment its key belongs to
+ * and the link has to reach the dashboard sitting in front of *that* one.
+ */
 export function frontendUrl(args) {
-  return args.value("--frontend", process.env.PREMAN_FRONTEND || DEFAULT_FRONTEND).replace(/\/+$/, "");
+  return args
+    .value("--frontend", process.env.PREMAN_FRONTEND || activeLogin(args)?.frontend_url || DEFAULT_FRONTEND)
+    .replace(/\/+$/, "");
 }
 
 /**
@@ -384,6 +417,14 @@ export function assertOk(result, action) {
   throw new Error(`${action} failed: ${result.status_code} ${detail}`);
 }
 
+function authSessionFrom(result, email) {
+  const user = result?.user && typeof result.user === "object" ? result.user : null;
+  return {
+    access_token: String(result?.access_token || ""),
+    user: user?.id != null ? { id: user.id, email: user.email || email } : { email },
+  };
+}
+
 async function verifyUnconfirmedAccount(args, email) {
   process.stdout.write("This email exists but is not verified. Sending a new OTP.\n");
   const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
@@ -391,7 +432,7 @@ async function verifyUnconfirmedAccount(args, email) {
   const otp = await promptText("Verification code: ");
   const verified = await callBackendJson(args, "POST", "/auth/verify-otp", { json: { email, otp } });
   assertOk(verified, "verify OTP");
-  return verified.access_token;
+  return authSessionFrom(verified, email);
 }
 
 /**
@@ -427,13 +468,13 @@ async function completeWithCode(args, email, otp, password) {
       json: { email, otp, new_password: password },
     });
     assertOk(setPassword, "set password");
-    return String(setPassword.access_token || "");
+    return authSessionFrom(setPassword, email);
   }
   const verified = await callBackendJson(args, "POST", "/auth/verify-otp", {
     json: { email, otp },
   });
   assertOk(verified, "verify OTP");
-  return String(verified.access_token || "");
+  return authSessionFrom(verified, email);
 }
 
 async function createAccountFromTerminal(args, email) {
@@ -468,7 +509,7 @@ async function createAccountFromTerminal(args, email) {
     json: { email, otp },
   });
   assertOk(verified, "verify OTP");
-  return String(verified.access_token || "");
+  return authSessionFrom(verified, email);
 }
 
 /**
@@ -481,6 +522,7 @@ export async function authenticateTerminal(args) {
     const creds = {
       api_key: explicitKey,
       backend_url: backendUrl(args),
+      frontend_url: frontendUrl(args),
       user_email: args.value("--email", ""),
       device_name: os.hostname(),
       created_at: new Date().toISOString(),
@@ -496,11 +538,11 @@ export async function authenticateTerminal(args) {
   const account = await callBackendJson(args, "GET", "/auth/needs-password", { query: { email } });
   assertOk(account, "check account");
 
-  let accessToken = "";
+  let session = { access_token: "", user: { email } };
 
   if (!account.exists) {
     process.stdout.write("No PreMan account found. Creating one now.\n");
-    accessToken = await createAccountFromTerminal(args, email);
+    session = await createAccountFromTerminal(args, email);
   } else if (account.needs_password) {
     // No password on this account, so a code is the only way in.
     const password = await optionalPassword(args);
@@ -508,7 +550,7 @@ export async function authenticateTerminal(args) {
     const resend = await callBackendJson(args, "POST", "/auth/resend-otp", { json: { email } });
     assertOk(resend, "resend OTP");
     const otp = await promptText("Verification code: ");
-    accessToken = await completeWithCode(args, email, otp, password);
+    session = await completeWithCode(args, email, otp, password);
   } else {
     const password = await promptSecret("Password (Enter to get a code by email): ");
     if (!password) {
@@ -516,22 +558,31 @@ export async function authenticateTerminal(args) {
       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, "");
+      session = await completeWithCode(args, email, otp, "");
     } else {
       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);
+        session = await verifyUnconfirmedAccount(args, email);
       } else {
         assertOk(login, "login");
-        accessToken = String(login.access_token || "");
+        session = authSessionFrom(login, email);
       }
     }
   }
 
+  const accessToken = String(session?.access_token || "");
   if (!accessToken) throw new Error("PreMan did not return an access token.");
 
+  let sessionUser = session.user && session.user.id != null ? session.user : null;
+  if (!sessionUser) {
+    const me = await callBackendJson(args, "GET", "/auth/me", { token: accessToken });
+    if (me.ok && me.id != null) {
+      sessionUser = { id: me.id, email: me.email || email, email_verified: me.email_verified };
+    }
+  }
+
   const keyName = `PreMan MCP CLI (${os.hostname()})`;
   const key = await callBackendJson(args, "POST", "/api-keys", {
     token: accessToken,
@@ -544,12 +595,24 @@ export async function authenticateTerminal(args) {
 
   const creds = {
     api_key: String(key.key),
+    access_token: accessToken,
+    user: sessionUser,
     backend_url: backendUrl(args),
+    frontend_url: frontendUrl(args),
     user_email: email,
     device_name: os.hostname(),
     created_at: new Date().toISOString(),
   };
-  saveStoredCredentials(creds);
+  saveStoredCredentials({
+    api_key: creds.api_key,
+    backend_url: creds.backend_url,
+    frontend_url: creds.frontend_url,
+    user_email: creds.user_email,
+    device_name: creds.device_name,
+    created_at: creds.created_at,
+  });
+  const { writeDesktopSession } = await import("./desktop.js");
+  writeDesktopSession(creds);
   return creds;
 }
 

package/bin/status.js

@@ -118,6 +118,41 @@ export function renderStatus(payload, { colour = false } = {}) {
     }
   }
 
+  // Between the endpoints and what was fixed, because it is the only section
+  // here that is asking for something. A repair PreMan wrote and nobody merged
+  // is invisible everywhere else in this command, which is how a fix ends up
+  // sitting on a branch for a fortnight while the endpoint it fixes keeps
+  // failing two lines further up.
+  const chase = payload.chase || {};
+  const waiting = chase.waiting_on_you || [];
+  if (waiting.length) {
+    lines.push("");
+    lines.push(`${paint.bold("Waiting on you")}`);
+    for (const entry of waiting) {
+      const label = truncate(entry.title || "fix", 40).padEnd(40);
+      const pr = entry.pr_url ? paint.blue(entry.pr_url) : paint.dim("no PR recorded");
+      lines.push(
+        `  ${paint.yellow("→")} ${label} ${pr} ${paint.dim(`${entry.waiting_for || entry.stage} · ${relativeTime(entry.since)}`)}`
+      );
+    }
+  }
+
+  // Split from `recently_fixed` on purpose. That list means "somebody marked it
+  // resolved"; this one means PreMan re-sent the request that was failing and
+  // production answered correctly, which is a different and much stronger claim.
+  const verified = chase.verified_in_production || [];
+  if (verified.length) {
+    lines.push("");
+    lines.push(`${paint.bold("Verified in production")} ${paint.dim("(7d)")}`);
+    for (const entry of verified) {
+      const label = truncate(entry.title || "fix", 40).padEnd(40);
+      const detail = entry.status ? `now returns ${entry.status}` : "re-ran clean";
+      lines.push(
+        `  ${paint.green("✓")} ${label} ${paint.dim(`${detail} · ${relativeTime(entry.since)}`)}`
+      );
+    }
+  }
+
   const fixed = payload.recently_fixed || [];
   if (fixed.length) {
     lines.push("");

package/bin/verify.js

@@ -24,9 +24,10 @@ import os from "node:os";
 import path from "node:path";
 
 import { changedFilesForPush, readChangedFiles, readPushRefsFromStdin, repoRoot } from "./changed.js";
-import { resolveLocalTarget } from "./detect.js";
+import { missingMountPrefix, resolveLocalTarget } from "./detect.js";
+import { formatDashboardLink, formatPushLink } from "./link.js";
 import { createReporter } from "./progress.js";
-import { backendUrl, callBackendJson, cliInvocation, makeArgs, nowMs, resolveApiKey } from "./shared.js";
+import { backendUrl, callBackendJson, cliInvocation, frontendUrl, makeArgs, nowMs, resolveApiKey } from "./shared.js";
 
 export const VERIFY_HELP = `
 Verify options:
@@ -278,7 +279,8 @@ async function fetchInventory(args, token) {
 }
 
 async function uploadRuns(args, { token, projectId, batchId, runs }) {
-  if (!projectId || !runs.length) return { inserted: 0, error: null };
+  if (!runs.length) return { inserted: 0, error: null };
+  if (!projectId) return { inserted: 0, error: null, unstored: "no_project" };
   let inserted = 0;
   for (let offset = 0; offset < runs.length; offset += UPLOAD_BATCH_SIZE) {
     const chunk = runs.slice(offset, offset + UPLOAD_BATCH_SIZE);
@@ -415,9 +417,29 @@ async function runPlan(
   const retarget = (url) =>
     origin && String(url).startsWith(origin) ? target.url + String(url).slice(origin.length) : url;
 
+  // A planned path can arrive without the prefix its router is mounted under.
+  // The plan is scanned from the pushed files alone, and the mount is normally
+  // declared in an untouched module as a variable no static scan can resolve,
+  // so the running app's spec is the only thing that knows. Correcting the URL
+  // is what makes the case reach the endpoint at all; correcting the reported
+  // path is what files the result under the route the developer wrote, since
+  // the uploaded run is keyed on `entry.path`. Uncorrected, an endpoint this
+  // push introduced is reported broken on a URL nobody wrote.
+  const mounted = (url, prefix) => {
+    const text = String(url);
+    return prefix && text.startsWith(target.url)
+      ? target.url + prefix + text.slice(target.url.length)
+      : text;
+  };
+  const planned = plan.selected.map((entry) => {
+    const prefix = missingMountPrefix(entry.method, entry.path, target.specRoutes) || "";
+    return { entry: prefix ? { ...entry, path: prefix + entry.path } : entry, prefix };
+  });
+  const remounted = planned.filter((item) => item.prefix).length;
+
   const work = [];
   let withheld = 0;
-  for (const entry of plan.selected) {
+  for (const { entry, prefix } of planned) {
     for (const testCase of entry.cases) {
       const method = String(testCase.method || "GET").toUpperCase();
       const mutating = !READ_METHODS.has(method) || testCase.effect === "mutating";
@@ -425,7 +447,7 @@ async function runPlan(
         withheld += 1;
         continue;
       }
-      work.push({ entry, testCase: { ...testCase, url: retarget(testCase.url) } });
+      work.push({ entry, testCase: { ...testCase, url: mounted(retarget(testCase.url), prefix) } });
     }
   }
 
@@ -465,6 +487,15 @@ async function runPlan(
         `${work.length} case${work.length === 1 ? "" : "s"}${policy.writes ? "" : ", read-only"}` +
         (plan.traffic?.available ? ", ranked by production traffic" : "")
     );
+    // Rewriting a URL the developer did not write is worth one line of output.
+    // Without it, a mount recovered from the spec is indistinguishable from a
+    // scan that got the path right, and the next person to debug a wrong prefix
+    // has no idea this step exists.
+    if (remounted) {
+      reporter.line(
+        `[preman] recovered the mount prefix for ${remounted} endpoint${remounted === 1 ? "" : "s"} from ${target.via}`
+      );
+    }
   }
 
   const runs = await runSlottedPool(
@@ -515,6 +546,12 @@ async function runPlan(
     if (withheld) reporter.line(`[preman] ${withheld} mutating case${withheld === 1 ? "" : "s"} withheld`);
     if (uploaded) reporter.line(`[preman] uploaded ${uploaded} run${uploaded === 1 ? "" : "s"}`);
     if (upload.error) reporter.line(`[preman] ${upload.error}`);
+    if (upload.unstored === "no_project") {
+      reporter.line(
+        `[preman] results not stored: this workspace has no linked project. ` +
+          `Link one at ${frontendUrl(args)}/settings to get a dashboard link here.`
+      );
+    }
     if (shouldBlock) {
       reporter.line(`[preman] blocking this push (${gate.from}). Set PREMAN_SKIP_HOOK=1 to override.`);
     } else if (breaking.length || removed.length) {
@@ -532,6 +569,16 @@ async function runPlan(
         : "";
       reporter.line(`[preman] ${found} — advisory only${disarmed}`);
     }
+    // Last, so it sits closest to git's own output. Only once something was
+    // stored: with no project the link would open an empty view.
+    if (uploaded) {
+      const link = formatPushLink({
+        batchId,
+        state: failed.length ? "failed" : "passed",
+        args,
+      });
+      if (link) reporter.line(link);
+    }
   }
 
   return {
@@ -563,6 +610,21 @@ async function runPlan(
   };
 }
 
+/**
+ * What the always-printed link should call itself.
+ *
+ * A scan in flight is the one state worth naming. It is the difference between
+ * "there is nothing here" and "there is nothing here yet", and the only one
+ * where the right response is to wait rather than to go and configure something.
+ */
+function dashboardLabel(scan) {
+  if (!scan?.running) return "\u25c6 PreMan \u00b7 view endpoints";
+  const found = Number(scan.findings) || 0;
+  return found
+    ? `\u25c6 PreMan \u00b7 scanning for endpoints \u2014 ${found} found so far`
+    : "\u25c6 PreMan \u00b7 scanning for endpoints";
+}
+
 async function runVerify(args) {
   const advisory = args.has("--pre-push");
   const asJson = args.has("--json");
@@ -571,9 +633,26 @@ async function runVerify(args) {
     1000;
   const deadline = Date.now() + budgetMs;
 
+  // Filled the moment `/cli/status` answers, and read by `finish` afterwards.
+  // Every early return happens either before that call or after it, so the only
+  // outcomes that see null are the ones where the backend never spoke -- for
+  // which "a scan is running" would be a claim we cannot make.
+  let scan = null;
+
   const finish = (outcome) => {
-    if (asJson) process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
-    else if (outcome.message) process.stdout.write(`${outcome.message}\n`);
+    if (asJson) {
+      process.stdout.write(`${JSON.stringify({ ...outcome, scan }, null, 2)}\n`);
+    } else {
+      if (outcome.message) process.stdout.write(`${outcome.message}\n`);
+      // Somewhere to look, whatever happened. The run-specific link is printed
+      // by the verify paths themselves, which have a batch to point at; this is
+      // the fallback for every outcome that does not, and it is the only output
+      // a skip would otherwise leave behind.
+      if (!outcome.uploaded) {
+        const link = formatDashboardLink({ args, label: dashboardLabel(scan) });
+        if (link) process.stdout.write(`${link}\n`);
+      }
+    }
     // A deliberate block is the one non-zero code advisory mode does not flatten.
     if ((!advisory || outcome.blocked) && outcome.exitCode) process.exitCode = outcome.exitCode;
     return outcome;
@@ -601,6 +680,7 @@ async function runVerify(args) {
     });
   }
   const projectId = status.workspace?.project_id || null;
+  scan = status.scan && typeof status.scan === "object" ? status.scan : null;
 
   const root = repoRoot();
   // The plan comes first so a brand-new endpoint — one this push introduces and
@@ -615,6 +695,21 @@ async function runVerify(args) {
 
   const { endpoints, error } = await fetchInventory(args, token);
   if ((error || !endpoints.length) && !planEndpoints.length) {
+    // An empty inventory during a scan is not the same answer as an empty one
+    // without a scan. Telling someone to run discovery while discovery is
+    // running sends them to do the thing already in progress.
+    if (!error && scan?.running) {
+      const found = Number(scan.findings) || 0;
+      return finish({
+        state: "skipped",
+        reason: "scan_in_progress",
+        message:
+          `[preman] skipped: endpoint discovery is still running` +
+          (found ? ` (${found} found so far)` : "") +
+          `. Push again once it finishes.`,
+        exitCode: 0,
+      });
+    }
     return finish({
       state: "skipped",
       reason: "no_inventory",
@@ -626,7 +721,15 @@ async function runVerify(args) {
   }
 
   const extraPorts = args.value("--port", "") ? [args.value("--port", "")] : [];
-  const confirmationEndpoints = planEndpoints.length ? planEndpoints : endpoints;
+  // Both sets, not the plan alone. The plan is here so a first-ever push can
+  // confirm a target with nothing saved yet, but consulting it *exclusively*
+  // hands a single route a veto over the whole check: a one-endpoint push whose
+  // mount prefix the scan could not resolve matches nothing in the live spec,
+  // scores 0/1, and the run is abandoned as "probably a different service" —
+  // exactly when the developer most wants the new endpoint exercised. Together,
+  // the saved inventory carries the identity question and the plan only adds to
+  // it. With an empty inventory this is still the plan on its own.
+  const confirmationEndpoints = [...endpoints, ...planEndpoints];
   const resolved = await resolveLocalTarget(confirmationEndpoints, {
     extraPorts,
     timeoutMs: 2000,
@@ -723,6 +826,20 @@ async function runVerify(args) {
     }
     if (uploaded) process.stdout.write(`[preman] uploaded ${uploaded} run${uploaded === 1 ? "" : "s"}\n`);
     if (upload.error) process.stdout.write(`[preman] ${upload.error}\n`);
+    if (upload.unstored === "no_project") {
+      process.stdout.write(
+        `[preman] results not stored: this workspace has no linked project. ` +
+          `Link one at ${frontendUrl(args)}/settings to get a dashboard link here.\n`
+      );
+    }
+    if (uploaded) {
+      const link = formatPushLink({
+        batchId,
+        state: failed.length ? "failed" : "passed",
+        args,
+      });
+      if (link) process.stdout.write(`${link}\n`);
+    }
   }
 
   return finish({ ...outcome, message: null });