@roadmapperai/mcp 0.9.0 → 0.9.3

package/README.md

@@ -126,6 +126,28 @@ This package follows semver. Breaking changes to tool shapes get a
 major-version bump and a deprecation window. Add `--package=@roadmapperai/mcp@0.x.y`
 to your `npx` invocation if you want to pin.
 
+Because the install is version-pinned (the dashboard hands you a config
+pinned to an exact version), the server checks the npm registry at boot
+and logs a one-line nudge to stderr if a newer version is published —
+re-copy the install command from **Settings → MCP** to upgrade. Disable
+the check with `ROADMAPPER_DISABLE_UPDATE_CHECK=1`.
+
+### Recent changes
+
+- **0.9.3** — new `link_repo` tool: when `get_active_workspace` reports
+  `env_default`/`unresolved` and you're in a git repo, one call persists
+  the repo → workspace mapping so future sessions resolve silently (the
+  repo slug is derived server-side; your API key pins the workspace).
+- **0.9.2** — `get_active_workspace` returns an explicit status envelope
+  (`resolved` / `ambiguous` / `env_default` / `unresolved`) with a `next`
+  action, instead of prose; surfaces multi-repo ambiguity.
+- **0.9.1** — the server now self-reports its real version (was a stale
+  hardcoded string in `serverInfo` and audit logs) and warns at boot
+  when a newer package is published.
+- **0.9.0** — entity reads on the customer path now route through the
+  broker, fixing an empty roadmap for every customer; new triage + gap
+  tools; light-by-default reads.
+
 ## Support
 
 - Bugs / feature requests: contact@roadmapperai.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadmapperai/mcp",
-  "version": "0.9.0",
+  "version": "0.9.3",
   "description": "Roadmapper AI MCP server — exposes a planning surface (themes, capabilities, tasks, sprints, PRs) to coding agents via stdio JSON-RPC. Pairs with the Roadmapper AI workspace at dashboard.roadmapperai.com.",
   "keywords": [
     "mcp",

package/server.mjs

@@ -95,7 +95,22 @@ const REPO_AGENTS_PATH = join(REPO, "AGENTS.md");
 
 const PROTOCOL_VERSION = "2024-11-05";
 const SERVER_NAME = "roadmapper";
-const SERVER_VERSION = "0.6.0";
+// Read the real version from the bundled package.json (it's in the npm
+// `files` allow-list) so SERVER_VERSION never drifts from the published
+// package. A hardcoded constant rotted to "0.6.0" while the package was
+// at 0.9.0 — which silently mis-stamped every audit-log row's
+// server_version. scripts/check-mcp-version.mjs guards the dashboard's
+// LATEST_MCP_VERSION against package.json; this closes the same gap on
+// the server side. Falls back to "0.0.0" only if the file is somehow
+// unreadable (never expected in a real install).
+const SERVER_VERSION = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(join(HERE, "package.json"), "utf-8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
 
 // Must match src/types.ts EFFORT_DAYS — AI-era calibration.
 // Fractional values (XS=0.25, S=0.5) get rounded up when used to
@@ -110,6 +125,69 @@ function log(...args) {
   console.error("[roadmapper-mcp]", ...args);
 }
 
+/**
+ * Compare two semver-ish strings ("1.2.3"). Returns 1 if a>b, -1 if
+ * a<b, 0 if equal. Compares the numeric major.minor.patch only — any
+ * prerelease/build suffix is ignored, which is fine for "is there a
+ * newer published release?" The probe below tolerates a 0 or negative
+ * result by staying silent, so an unexpected suffix never produces a
+ * false "upgrade available" nag.
+ */
+function compareVersions(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da > db) return 1;
+    if (da < db) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Best-effort startup staleness check. Fetches the `latest` dist-tag
+ * for @roadmapperai/mcp from the npm registry and, if the running
+ * version is behind, logs a one-line nudge to stderr. Entirely
+ * advisory — the server is pinned to a specific version in the
+ * client's MCP config (see the dashboard install snippets), so there
+ * is no auto-update; the user upgrades by re-copying the install
+ * command from Settings → MCP. This is the only signal a stranded,
+ * outdated install ever gets, so failures must stay silent (a flaky
+ * network or offline install must never spam the log or delay boot).
+ * Disable entirely with ROADMAPPER_DISABLE_UPDATE_CHECK=1.
+ */
+async function checkForUpdate() {
+  if (process.env.ROADMAPPER_DISABLE_UPDATE_CHECK === "1") return;
+  if (SERVER_VERSION === "0.0.0") return; // version unreadable; nothing to compare
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 2500);
+    let latest;
+    try {
+      const res = await fetch(
+        "https://registry.npmjs.org/@roadmapperai/mcp/latest",
+        { headers: { Accept: "application/json" }, signal: ctrl.signal }
+      );
+      if (!res.ok) return;
+      const body = await res.json();
+      latest = body && typeof body.version === "string" ? body.version : null;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!latest) return;
+    if (compareVersions(latest, SERVER_VERSION) > 0) {
+      log(
+        `update available: v${SERVER_VERSION} installed, v${latest} published. ` +
+          `This install is pinned — re-copy the install command from ` +
+          `Settings → MCP in the Roadmapper dashboard to upgrade.`
+      );
+    }
+  } catch {
+    // Offline, blocked, slow, or aborted — stay silent by design.
+  }
+}
+
 function send(message) {
   process.stdout.write(JSON.stringify(message) + "\n");
 }
@@ -509,6 +587,9 @@ function __setSnapshotWorkspaceForTest(value) {
 let _clientRoots = []; // array of absolute dir paths from the client
 let _rootWorkspace = undefined; // undefined=unresolved, null=resolved-but-none, string=workspaceId
 let _rootWorkspaceRepo = null; // the owner/repo that resolved (for diagnostics)
+let _rootWorkspaceMatches = []; // [{ ws, slug }] for EVERY mapped open root — kept
+// (not just the first) so get_active_workspace can report the ambiguous case
+// instead of silently committing to matches[0].
 let _clientSupportsRoots = false; // set from initialize params.capabilities.roots
 const ROOTS_LIST_REQUEST_ID = "roadmapper-roots-list"; // our id for the roots/list request we send
 
@@ -534,6 +615,7 @@ function setClientRoots(roots) {
   // Invalidate the cached resolution so the next access re-derives it.
   _rootWorkspace = undefined;
   _rootWorkspaceRepo = null;
+  _rootWorkspaceMatches = [];
 }
 
 /**
@@ -541,7 +623,21 @@ function setClientRoots(roots) {
  * to find the repo root implicitly via `git -C <dir>`. Returns null if
  * the dir isn't a git repo, has no origin, or git isn't available.
  */
+// Test seam: when set, repoSlugForDir returns this without shelling out
+// to git. Lets the selftest exercise link_repo deterministically (the
+// git call is environment-dependent and slow). Map of dir → slug, or a
+// bare string applied to any dir. null/undefined = real git resolution.
+let _repoSlugOverride = undefined;
+function __setRepoSlugForTest(v) {
+  _repoSlugOverride = v;
+}
+
 async function repoSlugForDir(dir) {
+  if (_repoSlugOverride !== undefined) {
+    return typeof _repoSlugOverride === "string"
+      ? _repoSlugOverride
+      : (_repoSlugOverride && _repoSlugOverride[dir]) || null;
+  }
   try {
     // Async so a slow/hanging git call never blocks the stdin event loop
     // (this runs while handling the client's roots/list reply). 2s cap.
@@ -620,6 +716,7 @@ async function resolveRootWorkspace() {
         `Pass workspaceId explicitly on calls to target a specific one.`
     );
   }
+  _rootWorkspaceMatches = matches;
   if (matches.length > 0) {
     _rootWorkspace = matches[0].ws;
     _rootWorkspaceRepo = matches[0].slug;
@@ -630,6 +727,24 @@ async function resolveRootWorkspace() {
   return null;
 }
 
+/**
+ * Distinct workspaces the currently-open roots map to, as
+ * `[{ workspaceId, repo }]`. Length > 1 means the resolution is
+ * ambiguous (two mapped repos open at once) and the caller picked the
+ * first — get_active_workspace surfaces this so the agent can pass an
+ * explicit workspaceId instead of trusting the silent first-match.
+ */
+function rootWorkspaceCandidates() {
+  const seen = new Set();
+  const out = [];
+  for (const m of _rootWorkspaceMatches) {
+    if (seen.has(m.ws)) continue;
+    seen.add(m.ws);
+    out.push({ workspaceId: m.ws, repo: m.slug });
+  }
+  return out;
+}
+
 /** Cached root-derived workspace id (sync read). null if none/unresolved. */
 function rootWorkspaceId() {
   return _rootWorkspace ?? null;
@@ -637,9 +752,11 @@ function rootWorkspaceId() {
 
 // Test hook: seed the root-resolution cache without touching the client
 // protocol or the network.
-function __setRootWorkspaceForTest(id, repo = null) {
+function __setRootWorkspaceForTest(id, repo = null, matches = null) {
   _rootWorkspace = id;
   _rootWorkspaceRepo = repo;
+  _rootWorkspaceMatches =
+    matches ?? (id ? [{ ws: id, slug: repo }] : []);
 }
 
 /**
@@ -964,13 +1081,29 @@ function compactResult(obj) {
  * concurrent agent writes safe — see migration 0006 for the
  * function bodies.
  */
+// A few write tools forward to a differently-named SECURITY DEFINER RPC
+// (the *_for_api_key convention). The broker has the matching map
+// (WRITE_RPC_ALIASES); we mirror it here so the operator path (direct
+// PostgREST, no broker) hits the same function name. Tools not listed
+// forward to an RPC of the same name (the common case).
+const RPC_ALIASES = {
+  link_repo: "link_repo_for_api_key",
+};
+
 async function rpcCall(fn, body) {
   const { url, writeKey, apiKey, brokerUrl } = supabaseConfig();
-  // body must already carry p_workspace_id — the per-tool resolver
-  // injects it before calling rpcCall so the override path works.
-  if (!url || !body?.p_workspace_id) {
+  if (!url) {
+    throw new Error("Write tools require ROADMAPPER_BACKEND_URL in env.");
+  }
+  // The body must carry p_workspace_id EXCEPT on the broker path, where
+  // the broker injects the validated workspace from the rmpr_ key (see
+  // link_repo, which deliberately omits it so the key's workspace wins
+  // rather than tripping the broker's cross-workspace guard). On the
+  // operator path there's no broker to supply it, so it's required.
+  const onBrokerPath = Boolean(apiKey && brokerUrl);
+  if (!onBrokerPath && !body?.p_workspace_id) {
     throw new Error(
-      "Write tools require ROADMAPPER_BACKEND_URL in env and a resolvable workspaceId (either ROADMAPPER_WORKSPACE_ID env or workspaceId arg)."
+      "Write tools require a resolvable workspaceId (either ROADMAPPER_WORKSPACE_ID env or workspaceId arg)."
     );
   }
 
@@ -1007,7 +1140,10 @@ async function rpcCall(fn, body) {
       "Write tools require either ROADMAPPER_API_KEY (customer path) or ROADMAPPER_ADMIN_KEY (operator path)."
     );
   }
-  const res = await fetch(`${url}/rest/v1/rpc/${fn}`, {
+  // Resolve the alias for the direct PostgREST call (the broker does this
+  // server-side for the customer path; the operator path goes direct).
+  const rpcName = RPC_ALIASES[fn] ?? fn;
+  const res = await fetch(`${url}/rest/v1/rpc/${rpcName}`, {
     method: "POST",
     headers: {
       apikey: writeKey,
@@ -1020,7 +1156,7 @@ async function rpcCall(fn, body) {
   if (!res.ok) {
     const txt = await res.text();
     throw new Error(
-      `rpc ${fn} failed: ${res.status} ${txt.slice(0, 300)}`
+      `rpc ${rpcName} failed: ${res.status} ${txt.slice(0, 300)}`
     );
   }
   return res.json();
@@ -1559,7 +1695,8 @@ const TOOLS = [
   {
     name: "get_active_workspace",
     description:
-      "Report the workspace this server will act on RIGHT NOW and HOW it was resolved — arg / .roadmapper snapshot / env default — plus whether writes are enabled and via which path (broker vs operator). Cheap: no roadmap data, no DB read.\n\n" +
+      "Report the workspace this server will act on RIGHT NOW and HOW it was resolved — arg / repo (git origin → repo_workspace_map) / .roadmapper snapshot / env default — plus whether writes are enabled and via which path (broker vs operator). Cheap: no roadmap data, no DB read.\n\n" +
+      "RETURNS a `status` (resolved | ambiguous | env_default | unresolved), `writesEnabled`, and a `next` action object (or null). Act only on status \"resolved\"; for any other status `next` carries the exact step to fix it (and `candidates` when a pick is needed) — surface it to the user as a one-tap choice rather than guessing.\n" +
       "USE WHEN: you're unsure which workspace is active; before the FIRST mutating call in a session; after changing directories. Especially important when the agent was launched outside a connected repo checkout, where the env default (often the seed workspace) silently wins.\n" +
       "PREREQUISITE: none — read-only.\n" +
       "ANTI-PATTERN: don't use it to inspect roadmap contents — that's get_roadmap_snapshot. This only answers 'where am I pointed'.\n" +
@@ -1576,6 +1713,21 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "link_repo",
+    description:
+      "Persist a mapping from the CURRENT git repo to your workspace, so future sessions in this repo resolve the workspace silently (no env default, no workspaceId arg). Your API key already pins ONE workspace, so this is a one-tap confirm — it links whatever repo you're in to that workspace.\n\n" +
+      "USE WHEN: get_active_workspace returns status \"env_default\" or \"unresolved\" while you ARE in a git repo, and you want writes to land in the right workspace going forward. This is the `next.onChoice` action those statuses point at.\n" +
+      "PREREQUISITE: the client must have shared a root (workspace folder) whose git origin resolves to an owner/name slug, and write auth must be configured (ROADMAPPER_API_KEY or operator key). The repo slug is derived server-side from your roots — you do NOT pass it.\n" +
+      "ANTI-PATTERN: don't call to switch an already-resolved workspace (it can't — your key pins one workspace); don't call outside a git repo (returns an actionable error). If the repo is already mapped to a DIFFERENT workspace, the call returns a conflict rather than stealing it.\n" +
+      "RETURNS status \"linked\" (mapping saved; resolution re-runs so the next call resolves from it), \"conflict\" (repo already maps elsewhere — surfaces the existing workspace), or an error result (no repo / no auth).\n" +
+      "EXAMPLE: link_repo()",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
   {
     name: "propose_task",
     description:
@@ -2218,21 +2370,111 @@ async function callTool(name, args) {
   if (name === "get_active_workspace") {
     const { id, source } = resolveWorkspaceWithSource(args?.workspaceId);
     const { url } = supabaseConfig();
-    let note;
-    if (source === "env") {
-      note =
-        "Resolved from the MCP install's env default — NOT from the current directory. If you meant a specific repo's workspace, launch from that checkout (connected repos carry .roadmapper/snapshot.json) or pass workspaceId explicitly.";
-    } else if (source === "none") {
-      note =
-        "No workspace resolved. Set ROADMAPPER_WORKSPACE_ID in env, run from a connected repo checkout, or pass workspaceId on the call.";
+    const mode = writeMode(); // "broker" | "operator" | "read-only"
+    const candidates = rootWorkspaceCandidates();
+    const ambiguous = source === "repo" && candidates.length > 1;
+
+    // Map resolution into ONE explicit status. Every state has a defined
+    // outcome and a `next` action the agent can act on directly — no prose
+    // the LLM has to interpret, no state where the answer is "I silently
+    // guessed". This is the contract a caller checks before its first write:
+    // act only on "resolved"; anything else carries the steps to fix it.
+    //   resolved     — arg / repo map / snapshot pinned it; safe to proceed
+    //   ambiguous    — several open repos map to different workspaces
+    //   env_default  — fell through to the install default (the #1 footgun)
+    //   unresolved   — nothing named a workspace at all
+    let status;
+    if (ambiguous) status = "ambiguous";
+    else if (source === "arg" || source === "repo" || source === "snapshot")
+      status = "resolved";
+    else if (source === "env") status = "env_default";
+    else status = "unresolved";
+
+    // `next`: the single recommended action, machine-shaped so the agent
+    // (or its harness) can turn it into a one-tap prompt. null when nothing
+    // is needed. `prompt` is phrased for a human; `candidates` (when set) is
+    // the pre-resolved pick list so the agent never has to ask open-ended.
+    let next = null;
+    if (status === "ambiguous") {
+      next = {
+        action: "pass_workspace_id",
+        prompt:
+          "Several open repos map to different workspaces. Which one do you mean?",
+        candidates,
+        detail:
+          "Resolution picked the first match. Pass workspaceId explicitly on the call to target a specific workspace.",
+      };
+    } else if (status === "env_default") {
+      next = {
+        action: "confirm_or_relocate",
+        prompt: `Act on the install default workspace "${id}"?`,
+        detail:
+          "Resolved from the MCP install's env default — NOT the current directory. If that's correct, proceed. Otherwise launch from the connected repo checkout (connected repos resolve via git origin → repo_workspace_map, or carry .roadmapper/snapshot.json) or pass workspaceId explicitly.",
+        // If the client shared a git root and writes are enabled, the
+        // agent can persist this repo → workspace in one tap so future
+        // sessions resolve silently (link_repo derives the slug itself).
+        ...(_clientRoots.length > 0 && mode !== "read-only"
+          ? {
+              onChoice: { tool: "link_repo", args: {} },
+              onChoicePrompt: `Link this repo to "${id}" so it resolves automatically next time?`,
+            }
+          : {}),
+      };
+    } else if (status === "unresolved") {
+      next = {
+        action: "configure_workspace",
+        prompt: "No workspace is resolvable. How should I target one?",
+        detail:
+          "Set ROADMAPPER_WORKSPACE_ID in env, run from a connected repo checkout, or pass workspaceId on the call.",
+        ...(_clientRoots.length > 0 && mode !== "read-only"
+          ? {
+              onChoice: { tool: "link_repo", args: {} },
+              onChoicePrompt:
+                "Link the repo you're in to your workspace so it resolves automatically next time?",
+            }
+          : {}),
+      };
     }
+
+    // Auth/write gate, reported separately from workspace resolution: a
+    // read-only install can resolve a workspace fine but still can't write.
+    // Surfacing it here lets the agent prompt for credentials BEFORE
+    // attempting a mutator, rather than after it's refused.
+    const writesEnabled = mode !== "read-only";
+    if (!writesEnabled) {
+      next = next ?? {
+        action: "set_credentials",
+        prompt: "Writes are disabled. Connect credentials to enable them?",
+        detail:
+          "Set ROADMAPPER_API_KEY (rmpr_ token from dashboard → Settings → MCP activity) to enable writes through the broker. The key pins exactly one workspace.",
+      };
+    }
+
+    // Back-compat prose for older callers that read `note`.
+    const note =
+      next && (status === "env_default" || status === "unresolved")
+        ? next.detail
+        : undefined;
+
     return textResult(
       JSON.stringify(
         {
           workspaceId: id,
-          resolvedFrom: source, // "arg" | "snapshot" | "env" | "none"
-          writeMode: writeMode(), // "broker" | "operator" | "read-only"
+          // "arg" | "repo" | "snapshot" | "env" | "none"
+          resolvedFrom: source,
+          status, // "resolved" | "ambiguous" | "env_default" | "unresolved"
+          writeMode: mode, // "broker" | "operator" | "read-only"
+          writesEnabled,
           backendConfigured: Boolean(url),
+          // Only report the repo that actually resolved the workspace —
+          // _rootWorkspaceRepo can hold a stale root match when an arg /
+          // snapshot / env value is what won.
+          repo: source === "repo" ? _rootWorkspaceRepo || null : null,
+          // Candidates only make sense when resolution was ambiguous;
+          // emitting them on a cleanly-resolved response reads as a
+          // contradiction to the agent consuming the envelope.
+          ...(status === "ambiguous" ? { candidates } : {}),
+          next, // recommended action (or null), pre-shaped for a prompt
           ...(note ? { note } : {}),
         },
         null,
@@ -2241,6 +2483,97 @@ async function callTool(name, args) {
     );
   }
 
+  // link_repo persists "this repo → my key's workspace" so future
+  // sessions resolve silently. Plumbing, not a roadmap write — exempt
+  // from the rubric/discovery gates (it's not in MUTATOR_TOOLS), and it
+  // returns before the projection read since it touches no roadmap data.
+  // The repo slug is derived server-side from the client's roots; the
+  // agent supplies nothing.
+  if (name === "link_repo") {
+    if (writeMode() === "read-only") {
+      return textResult(
+        JSON.stringify({
+          status: "no_auth",
+          error:
+            "Writes are disabled. Set ROADMAPPER_API_KEY (rmpr_ token from dashboard → Settings → MCP activity) to enable linking.",
+        })
+      );
+    }
+    // Find the first open root whose git origin resolves to a slug.
+    let slug = null;
+    for (const dir of _clientRoots) {
+      slug = await repoSlugForDir(dir);
+      if (slug) break;
+    }
+    if (!slug) {
+      return textResult(
+        JSON.stringify({
+          status: "no_repo",
+          error:
+            "Not in a git repo with an 'origin' remote (no resolvable owner/name slug from the client's roots). Open the repo you want to link as a workspace folder and retry.",
+        })
+      );
+    }
+    try {
+      // Workspace-id handling differs by path — link_repo is the one tool
+      // where it MUST:
+      //   • Broker (customer rmpr_) path: do NOT send p_workspace_id. The
+      //     broker's cross-workspace guard 403s when the body's
+      //     p_workspace_id != the key's validated workspace — and link_repo
+      //     is invoked exactly when resolution is env_default/unresolved,
+      //     i.e. when the MCP's resolved wsId is a guess that usually does
+      //     NOT match the key. Omitting it lets the broker inject the
+      //     validated workspace (the key pins it — that's the whole point).
+      //   • Operator path: no broker to inject, so pass the resolved wsId
+      //     to satisfy rpcCall's required-field guard + target the right
+      //     workspace. rpcCall throws (→ "error" result) if it's unresolved.
+      const body =
+        writeMode() === "broker"
+          ? { p_repo: slug }
+          : { p_workspace_id: wsId, p_repo: slug };
+      const res = await rpcCall("link_repo", body);
+      const result = Array.isArray(res) ? res[0] : res;
+      if (result?.status === "linked") {
+        // Force the next resolution to re-read repo_workspace_map so the
+        // freshly-linked mapping wins immediately (no stale cache).
+        _rootWorkspace = undefined;
+        _rootWorkspaceMatches = [];
+        _rootWorkspaceRepo = null;
+        return textResult(
+          JSON.stringify({
+            status: "linked",
+            repo: slug,
+            workspaceId: result.workspace_id ?? wsId,
+            detail:
+              "Mapping saved. This repo now resolves to your workspace on future calls.",
+          })
+        );
+      }
+      if (result?.status === "conflict") {
+        return textResult(
+          JSON.stringify({
+            status: "conflict",
+            repo: slug,
+            existingWorkspace: result.existing_workspace ?? null,
+            detail:
+              "This repo is already linked to a different workspace. It was not changed. Pass workspaceId explicitly if you need to act on a specific workspace.",
+          })
+        );
+      }
+      return textResult(
+        JSON.stringify({ status: "unknown", repo: slug, raw: result ?? null })
+      );
+    } catch (e) {
+      return textResult(
+        JSON.stringify({
+          status: "error",
+          repo: slug,
+          error: e instanceof Error ? e.message : String(e),
+        })
+      );
+    }
+  }
+
   // Post-Piece-6c, the entity tables ARE the canonical projection
   // — no edits blob, no seed-overlay merge. Fall back to the
   // bundled seed only when the DB is unreachable (offline / dev).
@@ -4465,8 +4798,16 @@ async function runSelftest() {
           const out = JSON.parse(r?.result?.content?.[0]?.text ?? "{}");
           return (
             typeof out.resolvedFrom === "string" &&
-            ["arg", "snapshot", "env", "none"].includes(out.resolvedFrom) &&
-            ["broker", "operator", "read-only"].includes(out.writeMode)
+            ["arg", "repo", "snapshot", "env", "none"].includes(
+              out.resolvedFrom
+            ) &&
+            ["broker", "operator", "read-only"].includes(out.writeMode) &&
+            ["resolved", "ambiguous", "env_default", "unresolved"].includes(
+              out.status
+            ) &&
+            // `next` is either null (resolved) or a shaped action object.
+            (out.next === null ||
+              (out.next && typeof out.next.action === "string"))
           );
         } catch {
           return false;
@@ -5864,6 +6205,42 @@ async function runSelftest() {
       pass: (r) =>
         r?.result?.id === "ws-from-snapshot" && r?.result?.source === "snapshot",
     },
+    {
+      // Two open repos mapping to DIFFERENT workspaces must not resolve
+      // silently to the first — get_active_workspace reports status
+      // "ambiguous" and hands back the candidate list so the agent can
+      // prompt for an explicit workspaceId instead of guessing.
+      name: "get_active_workspace surfaces ambiguous multi-repo resolution",
+      fn: () => {
+        try {
+          __setRootWorkspaceForTest("ws-a", "owner/repo-a", [
+            { ws: "ws-a", slug: "owner/repo-a" },
+            { ws: "ws-b", slug: "owner/repo-b" },
+          ]);
+          return handle({
+            id: 23,
+            method: "tools/call",
+            params: { name: "get_active_workspace", arguments: {} },
+          });
+        } finally {
+          __setRootWorkspaceForTest(undefined);
+        }
+      },
+      pass: (r) => {
+        try {
+          const out = JSON.parse(r?.result?.content?.[0]?.text ?? "{}");
+          return (
+            out.status === "ambiguous" &&
+            out.next?.action === "pass_workspace_id" &&
+            Array.isArray(out.candidates) &&
+            out.candidates.length === 2 &&
+            out.candidates.some((c) => c.workspaceId === "ws-b")
+          );
+        } catch {
+          return false;
+        }
+      },
+    },
     {
       // setClientRoots parses both file:// URIs and bare paths and
       // invalidates the cached resolution.
@@ -5880,6 +6257,149 @@ async function runSelftest() {
       // returns null until resolveRootWorkspace() runs. So "cleared" must be null.
       pass: (r) => r?.result?.cleared === null,
     },
+    {
+      // link_repo with no resolvable repo slug returns an actionable
+      // no_repo error rather than calling the broker.
+      name: "link_repo returns no_repo when not in a git repo",
+      fn: async () => {
+        const savedKey = process.env.ROADMAPPER_API_KEY;
+        const savedUrl = process.env.ROADMAPPER_BACKEND_URL;
+        try {
+          process.env.ROADMAPPER_API_KEY = "rmpr_selftest";
+          process.env.ROADMAPPER_BACKEND_URL = "https://selftest.local";
+          _clientRoots = ["/tmp/x"];
+          __setRepoSlugForTest(null); // no slug resolves
+          return await handle({
+            id: 91,
+            method: "tools/call",
+            params: { name: "link_repo", arguments: {} },
+          });
+        } finally {
+          __setRepoSlugForTest(undefined);
+          _clientRoots = [];
+          if (savedKey === undefined) delete process.env.ROADMAPPER_API_KEY;
+          else process.env.ROADMAPPER_API_KEY = savedKey;
+          if (savedUrl === undefined) delete process.env.ROADMAPPER_BACKEND_URL;
+          else process.env.ROADMAPPER_BACKEND_URL = savedUrl;
+        }
+      },
+      pass: (r) => {
+        try {
+          return JSON.parse(r?.result?.content?.[0]?.text ?? "{}").status === "no_repo";
+        } catch {
+          return false;
+        }
+      },
+    },
+    {
+      // link_repo with a resolvable slug POSTs { p_repo } through the
+      // broker and, on {status:"linked"}, invalidates the resolution
+      // cache. Stub fetch to assert the body shape + the linked result.
+      name: "link_repo posts slug to broker and reports linked",
+      fn: async () => {
+        const savedFetch = globalThis.fetch;
+        const savedKey = process.env.ROADMAPPER_API_KEY;
+        const savedUrl = process.env.ROADMAPPER_BACKEND_URL;
+        let sentBody = null;
+        try {
+          process.env.ROADMAPPER_API_KEY = "rmpr_selftest";
+          process.env.ROADMAPPER_BACKEND_URL = "https://selftest.local";
+          _clientRoots = ["/tmp/proj"];
+          __setRepoSlugForTest("acme/widget");
+          __setRootWorkspaceForTest("stale-ws"); // must be invalidated on link
+          globalThis.fetch = async (_u, opts) => {
+            sentBody = JSON.parse(opts.body);
+            return {
+              ok: true,
+              json: async () => ({ status: "linked", workspace_id: "ws-1", repo: "acme/widget" }),
+              text: async () => "",
+            };
+          };
+          const r = await handle({
+            id: 92,
+            method: "tools/call",
+            params: { name: "link_repo", arguments: {} },
+          });
+          return { r, sentBody, cacheCleared: _rootWorkspace };
+        } finally {
+          globalThis.fetch = savedFetch;
+          __setRepoSlugForTest(undefined);
+          __setRootWorkspaceForTest(undefined);
+          _clientRoots = [];
+          if (savedKey === undefined) delete process.env.ROADMAPPER_API_KEY;
+          else process.env.ROADMAPPER_API_KEY = savedKey;
+          if (savedUrl === undefined) delete process.env.ROADMAPPER_BACKEND_URL;
+          else process.env.ROADMAPPER_BACKEND_URL = savedUrl;
+        }
+      },
+      pass: (r) => {
+        try {
+          const out = JSON.parse(r?.r?.result?.content?.[0]?.text ?? "{}");
+          return (
+            out.status === "linked" &&
+            out.repo === "acme/widget" &&
+            // broker body carries the derived slug as p_repo
+            r?.sentBody?.rpc === "link_repo" &&
+            r?.sentBody?.body?.p_repo === "acme/widget" &&
+            // CRITICAL: on the broker path we must NOT send p_workspace_id —
+            // the broker injects the key's validated workspace, and sending
+            // a (likely mismatched) wsId would trip its cross-workspace
+            // guard and 403. This assertion locks in that fix.
+            r?.sentBody?.body?.p_workspace_id === undefined &&
+            // resolution cache invalidated so the new mapping wins next call
+            r?.cacheCleared === undefined
+          );
+        } catch {
+          return false;
+        }
+      },
+    },
+    {
+      // A repo already mapped to a different workspace returns the
+      // conflict passthrough (not a silent steal).
+      name: "link_repo surfaces conflict when repo maps elsewhere",
+      fn: async () => {
+        const savedFetch = globalThis.fetch;
+        const savedKey = process.env.ROADMAPPER_API_KEY;
+        const savedUrl = process.env.ROADMAPPER_BACKEND_URL;
+        const savedWs = process.env.ROADMAPPER_WORKSPACE_ID;
+        try {
+          process.env.ROADMAPPER_API_KEY = "rmpr_selftest";
+          process.env.ROADMAPPER_BACKEND_URL = "https://selftest.local";
+          process.env.ROADMAPPER_WORKSPACE_ID = "ws-mine";
+          _clientRoots = ["/tmp/proj"];
+          __setRepoSlugForTest("acme/taken");
+          globalThis.fetch = async () => ({
+            ok: true,
+            json: async () => ({ status: "conflict", existing_workspace: "ws-other" }),
+            text: async () => "",
+          });
+          return await handle({
+            id: 93,
+            method: "tools/call",
+            params: { name: "link_repo", arguments: {} },
+          });
+        } finally {
+          globalThis.fetch = savedFetch;
+          __setRepoSlugForTest(undefined);
+          _clientRoots = [];
+          if (savedKey === undefined) delete process.env.ROADMAPPER_API_KEY;
+          else process.env.ROADMAPPER_API_KEY = savedKey;
+          if (savedUrl === undefined) delete process.env.ROADMAPPER_BACKEND_URL;
+          else process.env.ROADMAPPER_BACKEND_URL = savedUrl;
+          if (savedWs === undefined) delete process.env.ROADMAPPER_WORKSPACE_ID;
+          else process.env.ROADMAPPER_WORKSPACE_ID = savedWs;
+        }
+      },
+      pass: (r) => {
+        try {
+          const out = JSON.parse(r?.result?.content?.[0]?.text ?? "{}");
+          return out.status === "conflict" && out.existingWorkspace === "ws-other";
+        } catch {
+          return false;
+        }
+      },
+    },
   ];
 
   let passed = 0;
@@ -5976,4 +6496,8 @@ if (process.argv.includes("--selftest")) {
     const snapTail = snap ? `, snapshot-workspace=${snap}` : "";
     log(`ready (mode=${mode}${tail}${snapTail})`);
   })();
+
+  // Advisory: nudge the operator if a newer package is published. Runs
+  // detached from boot — never blocks startup, never throws.
+  checkForUpdate();
 }