@roadmapperai/mcp 0.7.1 → 0.9.1

package/server.mjs

@@ -8,7 +8,12 @@
  * Customer-facing env vars (brand-named, no backend disclosure):
  *   ROADMAPPER_BACKEND_URL       — backend project URL
  *   ROADMAPPER_PUBLISHABLE_KEY   — public client key (RLS-scoped)
- *   ROADMAPPER_WORKSPACE_ID      — target workspace
+ *   ROADMAPPER_WORKSPACE_ID      — DEFAULT workspace (optional). With
+ *                                  one install serving many repos, the
+ *                                  server prefers the repo you're in
+ *                                  (see "Workspace resolution" below);
+ *                                  this env var is only the fallback for
+ *                                  repos with no mapping / no roots.
  *   ROADMAPPER_API_KEY           — write auth (rmpr_… token from
  *                                  Settings → MCP activity → API keys)
  *   ROADMAPPER_BROKER_URL        — optional override for the write
@@ -47,6 +52,17 @@
  *      validated server-side at the broker) or ROADMAPPER_ADMIN_KEY
  *      (operator path, bypasses RLS).
  *
+ * Workspace resolution (which workspace a tool call targets), in order:
+ *   1. Explicit `workspaceId` arg on the call.
+ *   2. The repo the agent is in: MCP `roots` → git origin → owner/repo →
+ *      `repo_workspace_map` (the mapping you set in the Roadmapper
+ *      GitHub-connect UI). This is what makes ONE install work across
+ *      MANY repos/workspaces — no per-repo config or env juggling.
+ *   3. `.roadmapper/snapshot.json` in cwd (committed offline fallback).
+ *   4. ROADMAPPER_WORKSPACE_ID env (the install default).
+ * Mismatch between an explicit arg and #2/#3 is refused (cross-workspace
+ * guard) unless ROADMAPPER_ALLOW_CROSS_WORKSPACE=1.
+ *
  * Self-test: `node mcp/server.mjs --selftest` exercises every tool
  * against the local seed and exits 0 on success, 1 on failure. Useful
  * for verifying the install without an MCP client.
@@ -58,6 +74,10 @@
 import { readFileSync, existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const REPO = resolve(HERE, "..");
@@ -75,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
@@ -90,10 +125,104 @@ 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");
 }
 
+/**
+ * Ask the client for its current roots (workspace folders). Server→client
+ * request; the reply arrives as a normal JSON-RPC response in the main
+ * read loop, routed by id to handleClientResponse(). No-op if the client
+ * never declared roots support.
+ */
+function requestClientRoots() {
+  if (!_clientSupportsRoots) return;
+  send({ jsonrpc: "2.0", id: ROOTS_LIST_REQUEST_ID, method: "roots/list" });
+}
+
+/**
+ * Handle a JSON-RPC *response* from the client (not a request). Only the
+ * roots/list reply matters today: record the roots, then re-resolve the
+ * root→workspace mapping and cache it for the sync resolvers.
+ */
+async function handleClientResponse(msg) {
+  if (msg.id !== ROOTS_LIST_REQUEST_ID) return;
+  if (msg.error) {
+    log("roots/list failed:", msg.error?.message ?? msg.error);
+    return;
+  }
+  const roots = msg.result?.roots ?? [];
+  setClientRoots(roots);
+  await resolveRootWorkspace();
+  const { id: ws, source, repo } = resolveWorkspaceWithSource();
+  if (source === "repo") {
+    log(`workspace resolved from repo ${repo} → ${ws}`);
+  }
+}
+
 function readSeed() {
   try {
     return JSON.parse(readFileSync(SEED_PATH, "utf-8"));
@@ -160,6 +289,49 @@ async function readAgentsMdForWorkspace() {
   return readAgentsMd();
 }
 
+/**
+ * Fetch the workspace's roadmap entities (pillars + capabilities +
+ * tasks) via the mcp-broker — the AUTHENTICATED read path for the
+ * customer (rmpr_) install.
+ *
+ * Why this exists: RLS (pillars_select_visible et al.) only grants
+ * SELECT to an authenticated workspace member (auth.uid()). The bare
+ * publishable key the MCP holds is the anon role with no user, so a
+ * direct PostgREST read returns ZERO rows for every workspace. The
+ * broker validates the rmpr_ key server-side and reads with the
+ * service role, scoped to that key's workspace — same pattern as the
+ * rubric/labels reads.
+ *
+ * Returns `{ pillars, capabilities, tasks }` (raw rows) on success, or
+ * null on any error / when no API key is set (operator path falls back
+ * to the direct service-role read in readWorkspaceProjected).
+ */
+async function fetchWorkspaceEntitiesViaBroker() {
+  const { apiKey, brokerUrl } = supabaseConfig();
+  if (!apiKey || !brokerUrl) return null;
+  try {
+    const res = await fetch(brokerUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "content-type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify({ rpc: "get_workspace_entities", body: {} }),
+    });
+    if (!res.ok) return null;
+    const parsed = await res.json();
+    if (!parsed || typeof parsed !== "object") return null;
+    return {
+      pillars: Array.isArray(parsed.pillars) ? parsed.pillars : [],
+      capabilities: Array.isArray(parsed.capabilities) ? parsed.capabilities : [],
+      tasks: Array.isArray(parsed.tasks) ? parsed.tasks : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Per-workspace label cache for tool descriptions.
  *
@@ -391,30 +563,228 @@ function __setSnapshotWorkspaceForTest(value) {
   _snapshotWorkspace = value;
 }
 
+// ── MCP roots → per-repo workspace resolution ───────────────────────
+//
+// THE PROBLEM this solves: a stdio MCP server is spawned ONCE by the
+// client (Claude Code) with a fixed process.cwd() — usually $HOME or
+// the first project the client opened. That cwd does NOT change as the
+// agent moves between repos. So the old `.roadmapper/snapshot.json in
+// cwd` resolution never fired for the common case: one MCP install,
+// many repos, each mapped to a different workspace. Everything fell
+// through to the single env default — silently polluting one workspace
+// with every repo's planning.
+//
+// THE FIX: MCP clients advertise `roots` (the workspace folders they're
+// operating in) at initialize and via notifications/roots/list_changed.
+// We capture those, derive each root's GitHub `owner/repo` from its git
+// remote, and look the repo up in `repo_workspace_map` — the SAME table
+// the Roadmapper GitHub-connect UI writes when you map a repo to a
+// workspace. So "which workspace is this repo?" is answered by the
+// server-side mapping the user already configured. Zero per-repo config.
+//
+// Resolution is async (DB lookup), but the per-call resolvers are sync,
+// so we resolve on initialize / roots-change and cache the result here.
+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 _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
+
+/** Convert a file:// root URI (or a plain path) to an absolute dir path. */
+function rootUriToPath(uri) {
+  if (typeof uri !== "string" || !uri) return null;
+  if (uri.startsWith("file://")) {
+    try {
+      return fileURLToPath(uri);
+    } catch {
+      return null;
+    }
+  }
+  return uri; // some clients send a bare path
+}
+
+/** Record the client's advertised roots (called from initialize + roots/list). */
+function setClientRoots(roots) {
+  if (!Array.isArray(roots)) return;
+  _clientRoots = roots
+    .map((r) => rootUriToPath(r?.uri ?? r))
+    .filter((p) => typeof p === "string" && p.length > 0);
+  // Invalidate the cached resolution so the next access re-derives it.
+  _rootWorkspace = undefined;
+  _rootWorkspaceRepo = null;
+}
+
+/**
+ * Derive `owner/repo` from a directory's git origin remote. Walks up
+ * 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.
+ */
+async function repoSlugForDir(dir) {
+  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.
+    const out = (
+      await execFileAsync("git", ["-C", dir, "remote", "get-url", "origin"], {
+        encoding: "utf8",
+        timeout: 2000,
+      })
+    ).stdout.trim();
+    // Normalize https + ssh forms to owner/repo:
+    //   https://github.com/owner/repo.git
+    //   git@github.com:owner/repo.git
+    const m = out.match(/[/:]([^/:]+\/[^/]+?)(?:\.git)?$/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Look up a repo slug in repo_workspace_map (enabled rows only) and
+ * return its workspace_id, or null. Read via the server's existing
+ * Supabase REST access (service-role key preferred so RLS doesn't hide
+ * the row). Best-effort — any failure resolves to null and we fall
+ * through to snapshot/env.
+ */
+async function workspaceForRepoSlug(slug) {
+  if (!slug) return null;
+  const { url, readKey: anonKey, writeKey } = supabaseConfig();
+  const key = writeKey || anonKey;
+  if (!url || !key) return null;
+  try {
+    const res = await fetch(
+      `${url}/rest/v1/repo_workspace_map?select=workspace_id&enabled=eq.true&repo=eq.${encodeURIComponent(
+        slug
+      )}&limit=1`,
+      { headers: { apikey: key, authorization: `Bearer ${key}` } }
+    );
+    if (!res.ok) return null;
+    const rows = await res.json();
+    return Array.isArray(rows) && rows[0]?.workspace_id
+      ? rows[0].workspace_id
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve (and cache) the workspace implied by the client's roots, by
+ * mapping each root's git repo through repo_workspace_map. Async; call
+ * from initialize / roots-change. Sync resolvers read the cached
+ * `_rootWorkspace`.
+ *
+ * Collects ALL mapped roots rather than first-match, so we can detect
+ * the ambiguous case — two mapped repos open at once (e.g. meridian +
+ * outerjoyn). When that happens we pick the first but LOG a warning,
+ * because silently guessing a workspace is the exact footgun this whole
+ * feature exists to kill. (A future client that tells us the active
+ * root could disambiguate; today the protocol gives us an unordered set.)
+ */
+async function resolveRootWorkspace() {
+  const matches = [];
+  for (const dir of _clientRoots) {
+    const slug = await repoSlugForDir(dir);
+    if (!slug) continue;
+    const ws = await workspaceForRepoSlug(slug);
+    if (ws) matches.push({ ws, slug });
+  }
+  const distinct = [...new Set(matches.map((m) => m.ws))];
+  if (distinct.length > 1) {
+    log(
+      `roots map to MULTIPLE workspaces (${matches
+        .map((m) => `${m.slug}→${m.ws}`)
+        .join(", ")}). Using "${matches[0].ws}". ` +
+        `Pass workspaceId explicitly on calls to target a specific one.`
+    );
+  }
+  if (matches.length > 0) {
+    _rootWorkspace = matches[0].ws;
+    _rootWorkspaceRepo = matches[0].slug;
+    return _rootWorkspace;
+  }
+  _rootWorkspace = null;
+  _rootWorkspaceRepo = null;
+  return null;
+}
+
+/** Cached root-derived workspace id (sync read). null if none/unresolved. */
+function rootWorkspaceId() {
+  return _rootWorkspace ?? null;
+}
+
+// Test hook: seed the root-resolution cache without touching the client
+// protocol or the network.
+function __setRootWorkspaceForTest(id, repo = null) {
+  _rootWorkspace = id;
+  _rootWorkspaceRepo = repo;
+}
+
 /**
  * Resolve the workspace id for a tool call. Resolution order:
  *   1. Explicit `workspaceId` arg on the call.
- *   2. `.roadmapper/snapshot.json` in the cwd (committed by the
- *      snapshot-roadmaps cron — names the workspace this repo
- *      belongs to).
- *   3. Env-driven `SUPABASE_WORKSPACE_ID`.
- *   4. null.
+ *   2. Client roots → git remote → repo_workspace_map (the repo the
+ *      agent is actually working in, mapped via the GitHub-connect UI).
+ *   3. `.roadmapper/snapshot.json` in the cwd (offline fallback).
+ *   4. Env-driven `SUPABASE_WORKSPACE_ID` (the install default).
+ *   5. null.
  *
- * Snapshot beats env because the snapshot reflects "where the agent
- * is right now", while the env reflects "where the operator pointed
- * the MCP install when they configured it". Cwd-specific wins.
+ * Roots beat snapshot beat env: roots reflect "the repo open right now"
+ * (most specific), snapshot reflects "this checkout's committed
+ * workspace", env reflects "where the operator pointed the install".
  *
  * Mutators with an explicit `workspaceId` arg that conflicts with the
- * cwd snapshot are refused upstream in `callTool` — see the
- * cross-workspace guard there.
+ * resolved repo/snapshot workspace are refused upstream in `callTool` —
+ * see the cross-workspace guard there.
  */
 function resolveWorkspaceId(argWorkspaceId) {
   if (argWorkspaceId) return argWorkspaceId;
+  const root = rootWorkspaceId();
+  if (root) return root;
   const snap = snapshotWorkspaceId();
   if (snap) return snap;
   return supabaseConfig().workspaceId ?? null;
 }
 
+// The workspace id a fresh install ships with — the bundled seed/demo
+// data lives here ("delete it once you add your own"). Mirrors the
+// VITE_SUPABASE_WORKSPACE_ID default in .env.example. Used by the
+// seed-workspace write guard to catch accidental writes to demo data.
+const SEED_WORKSPACE_ID = "default";
+
+/**
+ * Same resolution as resolveWorkspaceId, but also reports WHERE the id
+ * came from. The silent fall-through to the env default is the #1
+ * wrong-workspace footgun: launch the agent outside a connected repo
+ * checkout and every call quietly targets the install's env default
+ * (often the seed workspace) with nothing saying so. Surfacing the
+ * source — "arg" / "snapshot" / "env" / "none" — is the cheapest
+ * guardrail, and it feeds both get_active_workspace and the snapshot's
+ * resolvedFrom field.
+ */
+function resolveWorkspaceWithSource(argWorkspaceId) {
+  if (argWorkspaceId) return { id: argWorkspaceId, source: "arg" };
+  const root = rootWorkspaceId();
+  if (root) return { id: root, source: "repo", repo: _rootWorkspaceRepo };
+  const snap = snapshotWorkspaceId();
+  if (snap) return { id: snap, source: "snapshot" };
+  const envWs = supabaseConfig().workspaceId;
+  if (envWs) return { id: envWs, source: "env" };
+  return { id: null, source: "none" };
+}
+
+/**
+ * Which write path is active, for diagnostics. The customer path
+ * (rmpr_ key → mcp-broker) keeps the service-role key off this machine;
+ * the operator path holds a service-role-equivalent key locally.
+ */
+function writeMode() {
+  const { apiKey, writeKey } = supabaseConfig();
+  if (apiKey) return "broker"; // rmpr_ key, validated server-side
+  if (writeKey) return "operator"; // service-role-equivalent key, local
+  return "read-only";
+}
+
 /**
  * Read the workspace's current entity state directly from the
  * normalized tables (Stage 3 Piece 6c — `workspaces.edits` column
@@ -426,8 +796,31 @@ function resolveWorkspaceId(argWorkspaceId) {
  * agent reads down to the caller's visible_pillars allow-list.
  */
 async function readWorkspaceProjected(wsIdOverride) {
-  const { url, readKey: anonKey, writeKey } = supabaseConfig();
+  const { url, readKey: anonKey, writeKey, apiKey } = supabaseConfig();
   const workspaceId = resolveWorkspaceId(wsIdOverride);
+
+  // Customer path: when an rmpr_ API key is set, read through the broker.
+  // A direct PostgREST read with the publishable (anon) key returns zero
+  // rows — RLS only grants SELECT to authenticated workspace members. The
+  // broker authenticates the key server-side and reads (service role)
+  // scoped to THAT key's workspace. The key pins one workspace, so a
+  // wsIdOverride for a different workspace isn't readable on the customer
+  // path anyway — the broker correctly returns the key's workspace, and
+  // the cross-workspace guard upstream already blocks writes elsewhere.
+  if (apiKey) {
+    const ent = await fetchWorkspaceEntitiesViaBroker();
+    if (ent) {
+      return {
+        themes: ent.pillars.map(rowToThemeProjected),
+        capabilities: ent.capabilities.map(rowToCapabilityProjected),
+        tasks: ent.tasks.map(rowToTaskProjected),
+      };
+    }
+    // Broker failed — fall through to the direct read below. On a pure
+    // customer install (anon key only) that returns null; operator
+    // installs that ALSO set a service key still get a working read.
+  }
+
   const key = writeKey || anonKey;
   if (!url || !key || !workspaceId) return null;
   const filter = `workspace_id=eq.${encodeURIComponent(workspaceId)}`;
@@ -556,6 +949,91 @@ function stripUndefined(o) {
   return o;
 }
 
+// ---- Token-efficiency: light projections + pagination ----------------
+//
+// Read tools return light rows BY DEFAULT (detail:true opts into full
+// rows). The heavy fields — prs[], acceptance[], acceptanceGrades[],
+// outcomeReadings[], dependsOn[], and long summary/description text —
+// are ~95% of a row's token cost on a large workspace, so dropping
+// them turns a naive list_tasks() from ~81KB into <1KB. The cap is a
+// backstop, not the lever; the projection is.
+
+const LIST_DEFAULT_LIMIT = 50;
+const LIST_MAX_LIMIT = 200;
+
+// Light task row: identity + the fields you triage on. No prs/
+// acceptance/summary. summary is replaced by a presence flag so the
+// agent knows detail exists without paying for it.
+function taskLight(t) {
+  return stripUndefined({
+    id: t.id,
+    title: t.title,
+    status: t.status,
+    priority: t.priority,
+    effort: t.effort,
+    kind: t.kind,
+    capabilityId: t.capabilityId,
+    pillarId: t.pillarId,
+    owner: t.owner,
+    prCount: Array.isArray(t.prs) ? t.prs.length : undefined,
+    hasSummary: t.summary ? true : undefined,
+    archived: t.archived,
+  });
+}
+
+// Light capability row: identity + status signals. No
+// outcomeReadings[]/dependsOn[]/description. outcome kept — it's the
+// one field the agent needs to judge fit, and it's bounded text.
+//
+// status is the EFFECTIVE status (derived from child tasks when the
+// row has no explicit status), so the light row agrees with how the
+// snapshot/list filters decided to include it. Pass `tasks` to enable
+// the derivation; without it we fall back to the raw column (which is
+// often null — that's the bug this guards against).
+function capabilityLight(c, tasks) {
+  return stripUndefined({
+    id: c.id,
+    pillarId: c.pillarId,
+    name: c.name,
+    status: tasks ? effectiveCapabilityStatus(c, tasks) : c.status,
+    outcome: c.outcome,
+    outcomeStatus: c.outcomeStatus,
+    roi: c.roi,
+    target: c.target,
+    archived: c.archived,
+  });
+}
+
+// Clamp a requested limit to [1, LIST_MAX_LIMIT], default 50.
+function clampLimit(raw) {
+  const n = Number.isFinite(raw) ? Math.floor(raw) : LIST_DEFAULT_LIMIT;
+  return Math.min(LIST_MAX_LIMIT, Math.max(1, n));
+}
+
+// Apply limit + light/full projection to a row list and wrap with a
+// {total, returned, truncated} envelope so the agent knows whether to
+// narrow its filter rather than page blindly.
+function paginateRows(rows, args, lightFn, ctx) {
+  const limit = clampLimit(args?.limit);
+  const detail = args?.detail === true;
+  const sliced = rows.slice(0, limit);
+  return {
+    total: rows.length,
+    returned: sliced.length,
+    truncated: rows.length > sliced.length,
+    // ctx is passed through to the mapper (capabilityLight uses it to
+    // derive effective status from tasks); taskLight ignores it.
+    items: detail ? sliced : sliced.map((r) => lightFn(r, ctx)),
+  };
+}
+
+// Compact JSON (no 2-space pretty-print) — pretty-printing is ~20-30%
+// pure-whitespace tokens across every list return. Humans read these
+// through a client that re-formats; the wire form should be compact.
+function compactResult(obj) {
+  return textResult(JSON.stringify(obj));
+}
+
 /**
  * Invoke a Postgres function exposed via PostgREST. Used by the
  * write tools so the read-modify-write happens inside a single
@@ -802,11 +1280,25 @@ function validateConfidence(confidence) {
  * parent theme's target. Caller can still proceed — but the
  * warning surfaces in dryRun output so the agent can rethink.
  */
+// Compact dollar formatter (ROI is stored as RAW DOLLARS). Local copy
+// of src/lib/util.ts formatCompactMoney — the .mjs can't import the TS.
+function fmtMoney(dollars) {
+  if (dollars == null || !Number.isFinite(dollars) || dollars <= 0) return "$0";
+  const f = (n, s) => {
+    const r = Math.round(n * 10) / 10;
+    return `$${Number.isInteger(r) ? r.toFixed(0) : r.toFixed(1)}${s}`;
+  };
+  if (dollars < 1e3) return `$${Math.round(dollars)}`;
+  if (dollars < 1e6) return f(dollars / 1e3, "K");
+  if (dollars < 1e9) return f(dollars / 1e6, "M");
+  return f(dollars / 1e9, "B");
+}
+
 function warnRoiVsTheme(roi, theme) {
   if (roi == null || theme?.targetRoi == null) return null;
   const floor = theme.targetRoi * 0.7;
   if (roi < floor) {
-    return `roi $${roi}M is well below 70% of theme "${theme.name}" target ($${theme.targetRoi}M). Justify the gap in your outcome, or rethink the parent theme.`;
+    return `roi ${fmtMoney(roi)} is well below 70% of theme "${theme.name}" target (${fmtMoney(theme.targetRoi)}). Justify the gap in your outcome, or rethink the parent theme.`;
   }
   return null;
 }
@@ -996,7 +1488,7 @@ const TOOLS = [
   {
     name: "list_capabilities",
     description:
-      "List active capabilities (quarterly bets). Excludes delivered and archived capabilities by default — agents should target work that's still in flight.\n\n" +
+      "List active capabilities (quarterly bets). Excludes delivered and archived capabilities by default — agents should target work that's still in flight. Returns LIGHT rows by default (id/pillarId/name/status/outcome/outcomeStatus/roi/target), capped at 50; pass detail:true for full rows incl. outcomeReadings/dependsOn/description. Response envelope: { total, returned, truncated, items }.\n\n" +
       "USE WHEN: planning a feature and need to find the right parent capability, reviewing in-flight bets, or scoping what's still on the table this quarter.\n" +
       "PREREQUISITE: none — read-only. For routing a specific work description, prefer suggest_capability_for which ranks by token overlap.\n" +
       "ANTI-PATTERN: do not call to find a capability when you already know its id (use get_roadmap_snapshot for richer context). Pass includeDelivered=true or includeArchived=true only when reviewing historical bets — almost never in a planning session.\n" +
@@ -1007,6 +1499,17 @@ const TOOLS = [
         themeId: { type: "string" },
         includeDelivered: { type: "boolean" },
         includeArchived: { type: "boolean" },
+        detail: {
+          type: "boolean",
+          description:
+            "Return full capability rows (outcomeReadings, dependsOn, description) instead of light rows. Default false.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 200,
+          description: "Max rows to return. Default 50, hard cap 200.",
+        },
         workspaceId: { type: "string" },
       },
       additionalProperties: false,
@@ -1015,10 +1518,10 @@ const TOOLS = [
   {
     name: "list_tasks",
     description:
-      "List tasks. Filter by capabilityId or status. Excludes archived tasks by default.\n\n" +
+      "List tasks. Filter by capabilityId or status. Excludes archived tasks by default. Returns LIGHT rows by default (id/title/status/priority/effort/kind/capabilityId/owner + prCount + hasSummary), capped at 50; pass detail:true for full rows incl. prs/acceptance/summary, and limit to raise the cap (max 200). The response is an envelope: { total, returned, truncated, items }.\n\n" +
       "USE WHEN: surveying what already exists under a capability before proposing a new task (avoid duplicates), reviewing a status bucket (e.g. all in_progress), or answering 'what's open right now'.\n" +
       "PREREQUISITE: none — read-only.\n" +
-      "ANTI-PATTERN: do not call to track in-progress work within a single conversation — use the harness TodoWrite tool. Do not call without a filter when the workspace has many tasks; scope by capabilityId or status. Pass includeArchived=true only when reviewing closed history.\n" +
+      "ANTI-PATTERN: do not call to track in-progress work within a single conversation — use the harness TodoWrite tool. If truncated:true, NARROW the filter (capabilityId/status) rather than cranking limit — light rows are cheap but full detail on hundreds of rows is not. Reach for detail:true only when you actually need prs/acceptance, ideally with a filter.\n" +
       "EXAMPLE: list_tasks({ capabilityId: 'CAP-XXX', status: 'in_progress' })",
     inputSchema: {
       type: "object",
@@ -1029,6 +1532,49 @@ const TOOLS = [
           enum: ["delivered", "in_progress", "planned", "exploring"],
         },
         includeArchived: { type: "boolean" },
+        detail: {
+          type: "boolean",
+          description:
+            "Return full task rows (prs, acceptance, acceptanceGrades, summary, dependsOn) instead of light rows. Default false.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 200,
+          description: "Max rows to return. Default 50, hard cap 200.",
+        },
+        workspaceId: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_uncategorized_tasks",
+    description:
+      "List tasks with no parent capability (capabilityId is null) — the orphans the GitHub webhook auto-created from PRs that carried no Roadmapper-Capability trailer and matched no capability. Excludes archived tasks by default.\n\n" +
+      "USE WHEN: triaging the roadmap — finding work that shipped but never got filed under a quarterly bet, so it's invisible in capability rollups, burndown, and the outlook view. Pair with suggest_capability_for({ taskId }) to find each one's best-fit home, then move_task to file it.\n" +
+      "PREREQUISITE: none — read-only.\n" +
+      "ANTI-PATTERN: do not use to list ALL tasks — that's list_tasks. This is specifically the unparented backlog. A long result here is a signal that PRs aren't carrying capability trailers, not that you should ignore it.\n" +
+      "EXAMPLE: list_uncategorized_tasks({ status: 'in_progress' })",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: ["delivered", "in_progress", "planned", "exploring"],
+        },
+        includeArchived: { type: "boolean" },
+        detail: {
+          type: "boolean",
+          description:
+            "Return full task rows instead of light rows. Default false.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 200,
+          description: "Max rows to return. Default 50, hard cap 200.",
+        },
         workspaceId: { type: "string" },
       },
       additionalProperties: false,
@@ -1065,10 +1611,10 @@ const TOOLS = [
   {
     name: "get_roadmap_snapshot",
     description:
-      "Single-call orient: themes + active capabilities + in-flight tasks for the workspace, plus the resolved workspaceId. Always live. Excludes archived entities by default.\n\n" +
+      "Single-call orient: themes + active capabilities + in-flight tasks for the workspace, plus the resolved workspaceId. Always live. Excludes archived entities by default. Returns LIGHT rows by default and caps the task list at 50 (the counts block always carries true totals); pass detail:true for full rows. Response carries mode ('summary'|'detail') and tasksTruncated.\n\n" +
       "USE WHEN: starting fresh in a workspace and need the whole canonical model in one read, or before opening a PR to confirm which workspace + capability to attach to.\n" +
       "PREREQUISITE: none — read-only. Often the very first call after get_agents_md.\n" +
-      "ANTI-PATTERN: do not call repeatedly within one planning pass; the data doesn't change inside a single session. Use list_tasks / list_capabilities if you need just one slice. Pass includeArchived=true only when surveying historical state.\n" +
+      "ANTI-PATTERN: do not call repeatedly within one planning pass; the data doesn't change inside a single session. Avoid detail:true on large workspaces — use list_tasks with a filter for the rows you actually need. Pass includeArchived=true only when surveying historical state.\n" +
       "EXAMPLE: get_roadmap_snapshot()",
     inputSchema: {
       type: "object",
@@ -1079,6 +1625,31 @@ const TOOLS = [
             "Optional. Override the env-default workspace. Useful when the agent is operating against a .roadmapper/snapshot.json that names its own workspace.",
         },
         includeArchived: { type: "boolean" },
+        detail: {
+          type: "boolean",
+          description:
+            "Return full theme/capability/task rows instead of light ones. Default false. Can be large on big workspaces.",
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    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" +
+      "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" +
+      "EXAMPLE: get_active_workspace()",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description:
+            "Optional. Resolve as if this override were passed to a real call, to preview which workspace it would target.",
+        },
       },
       additionalProperties: false,
     },
@@ -1092,7 +1663,7 @@ const TOOLS = [
       "ANTI-PATTERN: do not call to track in-progress work within a single conversation — use the harness TodoWrite tool. Do not call to log a bug discovered during implementation — file in the issue tracker, not roadmapper. Do not call when you don't know which capability the task belongs under; resolve that first.\n" +
       "REQUIRED FIELDS: capabilityId, title, effort. Always size the task — XS (≤2h) / S (≤1d) / M (~1-3d) / L (~1-2w) / XL (>2w). Effort drives capability % roll-up weighting; do not omit.\n" +
       "EXAMPLE: propose_task({ capabilityId: 'CAP-XXX', title: 'Drag-and-drop block reorder', effort: 'M', acceptance: ['Block can be dragged with mouse + keyboard', 'Order persists across reloads'], idempotencyKey: 'session-1-task-3' })\n\n" +
-      "Requires SUPABASE_SERVICE_ROLE_KEY. Pass idempotencyKey so retries don't duplicate. Pass dryRun: true to validate without writing. Pass workspaceId to target a workspace other than the env default.",
+      "Requires write auth (set ROADMAPPER_API_KEY). Pass idempotencyKey so retries don't duplicate. Pass dryRun: true to validate without writing. Pass workspaceId to target a workspace other than the env default.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1130,15 +1701,15 @@ const TOOLS = [
       "USE WHEN: the work the user is describing genuinely doesn't fit ANY existing theme, AND the user explicitly says they want a new strategic direction. Almost never the right answer in a planning session.\n" +
       "PREREQUISITE: get_agents_md once this session (enforced). Theme discovery once this session, satisfied by suggest_theme_for (preferred — returns ranked matches with a fit signal), list_themes, or get_roadmap_snapshot. Enforced — the server returns discovery_missing with a fix field if you skip it. Duplicating a theme is the most common failure mode; the gate stops it.\n" +
       "ANTI-PATTERN: do not call to organize a quarter of work — that's a capability, not a theme. Do not call because the existing themes feel too coarse — they're SUPPOSED to be coarse. Use propose_capability under an existing theme instead.\n" +
-      "EXAMPLE: propose_theme({ name: 'AI Agent Reliability', description: 'Multi-year bet on making agent workflows reproducible.', targetRoi: 20, idempotencyKey: 'session-1-theme-1' })\n\n" +
-      "Requires SUPABASE_SERVICE_ROLE_KEY. Pass idempotencyKey so retries don't duplicate. Pass dryRun: true to validate without writing. Pass workspaceId to target a workspace other than the env default.",
+      "EXAMPLE: propose_theme({ name: 'AI Agent Reliability', description: 'Multi-year bet on making agent workflows reproducible.', targetRoi: 20000000, idempotencyKey: 'session-1-theme-1' })\n\n" +
+      "Requires write auth (set ROADMAPPER_API_KEY). targetRoi is RAW ANNUAL DOLLARS (e.g. 20000000 = $20M), not millions. Pass idempotencyKey so retries don't duplicate. Pass dryRun: true to validate without writing. Pass workspaceId to target a workspace other than the env default.",
     inputSchema: {
       type: "object",
       properties: {
         name: { type: "string" },
         description: { type: "string" },
         color: { type: "string" },
-        targetRoi: { type: "number" },
+        targetRoi: { type: "number", description: "Annual ROI target in raw dollars (e.g. 20000000 = $20M)." },
         idempotencyKey: { type: "string" },
         dryRun: { type: "boolean" },
         workspaceId: { type: "string" },
@@ -1155,7 +1726,7 @@ const TOOLS = [
       "PREREQUISITE: get_agents_md once this session (enforced). suggest_capability_for (or list_capabilities / get_roadmap_snapshot / the roadmapper://capabilities/active resource) once this session (enforced — server returns discovery_missing with a fix field if you skip it). The server WILL also reject if token overlap with an existing capability is too high; the gate is upstream of that.\n" +
       "ANTI-PATTERN: do not call for a single deliverable — that's a task. Do not call when the outcome is fuzzy ('improve X') — the server rejects non-falsifiable outcomes. Do not call when an existing capability is close-enough; capabilities cost human attention to maintain.\n" +
       "EXAMPLE: propose_capability({ pillarId: 'TH-XXX', name: 'Self-serve landing page builder', outcome: 'Customers publish a landing page in under 5 minutes without engineering involvement.', reach: 200, impact: 1, confidence: 70, idempotencyKey: 'session-1-cap-1' })\n\n" +
-      "Server rejects empty / non-falsifiable outcomes, confidence >95, and names <8 chars. Requires SUPABASE_SERVICE_ROLE_KEY. Pass idempotencyKey, dryRun, workspaceId as for propose_task.",
+      "Server rejects empty / non-falsifiable outcomes, confidence >95, and names <8 chars. Requires write auth (set ROADMAPPER_API_KEY). Pass idempotencyKey, dryRun, workspaceId as for propose_task.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1166,7 +1737,7 @@ const TOOLS = [
         reach: { type: "number" },
         impact: { type: "number", enum: [3, 2, 1, 0.5, 0.25] },
         confidence: { type: "number", minimum: 0, maximum: 100 },
-        roi: { type: "number" },
+        roi: { type: "number", description: "Estimated annual ROI in raw dollars (e.g. 2500000 = $2.5M)." },
         specRef: { type: "string" },
         idempotencyKey: { type: "string" },
         dryRun: { type: "boolean" },
@@ -1184,7 +1755,7 @@ const TOOLS = [
       "PREREQUISITE: get_agents_md once this session (enforced — defines grading dimensions). Call get_task first to read the acceptance criteria in order — indexes are positional.\n" +
       "ANTI-PATTERN: do not call before the implementation actually works — fabricated passes destroy the trust this signal carries. Do not call without a note when status='fail' — the reviewer needs the failure mode.\n" +
       "EXAMPLE: submit_acceptance_grades({ taskId: 'TK-100201', grades: [{ index: 0, status: 'pass' }, { index: 1, status: 'fail', note: 'Reload-persistence is flaky on Firefox; tracked in TK-100202' }] })\n\n" +
-      "Requires SUPABASE_SERVICE_ROLE_KEY. Pass workspaceId to target a workspace other than the env default.",
+      "Requires write auth (set ROADMAPPER_API_KEY). Pass workspaceId to target a workspace other than the env default.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1211,19 +1782,23 @@ const TOOLS = [
   {
     name: "suggest_capability_for",
     description:
-      "Given a free-text description of work, return the top existing capabilities ranked by token overlap.\n\n" +
-      "USE WHEN: about to propose tasks or a capability — call this FIRST to find an existing parent. If any returned score > 0.4, strongly prefer attaching tasks there over creating a new capability.\n" +
+      "Return the top existing capabilities ranked by token overlap with either a free-text description OR an existing task (pass taskId and the server synthesizes the query from the task's title + summary).\n\n" +
+      "USE WHEN: about to propose tasks or a capability — call this FIRST to find an existing parent. If any returned score > 0.4, strongly prefer attaching tasks there over creating a new capability. With taskId, this is the triage companion to list_uncategorized_tasks: rank a home for an orphaned task, then move_task it.\n" +
       "PREREQUISITE: none — read-only.\n" +
-      "ANTI-PATTERN: do not call after you've already decided to create a new capability — that's the case this tool is meant to prevent. Do not interpret weak matches (<0.2) as fits; if nothing's close, propose_capability is the right next call (after confirming with the user).\n" +
-      "EXAMPLE: suggest_capability_for({ description: 'multi-tenant landing page builder with drag-and-drop blocks' })",
+      "ANTI-PATTERN: do not call after you've already decided to create a new capability — that's the case this tool is meant to prevent. Do not interpret weak matches (<0.2) as fits; if nothing's close, propose_capability is the right next call (after confirming with the user). Pass exactly one of description / taskId.\n" +
+      "EXAMPLE: suggest_capability_for({ description: 'multi-tenant landing page builder with drag-and-drop blocks' }) — or — suggest_capability_for({ taskId: 'TK-100201' })",
     inputSchema: {
       type: "object",
       properties: {
         description: { type: "string" },
+        taskId: {
+          type: "string",
+          description:
+            "TK-NNNNNN. When set, the query is built from the task's title + summary. Mutually exclusive with description.",
+        },
         limit: { type: "integer", minimum: 1, maximum: 25 },
         workspaceId: { type: "string" },
       },
-      required: ["description"],
       additionalProperties: false,
     },
   },
@@ -1255,7 +1830,7 @@ const TOOLS = [
       "PREREQUISITE: get_agents_md once this session (enforced). The task id must exist (get_task / list_tasks to confirm).\n" +
       "ANTI-PATTERN: do not call as a substitute for the Roadmapper-Task: PR-body trailer convention — the trailer is the durable contract; link_pr is the instant-feedback shortcut. Do not call for PRs that don't have a parent task in roadmapper.\n" +
       "EXAMPLE: link_pr({ taskId: 'TK-100201', repo: 'acme/frontend', number: 1234, title: 'Drag block reorder', authorGithub: 'octocat' })\n\n" +
-      "Idempotent by (repo, number) — re-calling with an already-linked PR returns idempotent:true. Requires SUPABASE_SERVICE_ROLE_KEY. Pass workspaceId to target a workspace other than the env default.",
+      "Idempotent by (repo, number) — re-calling with an already-linked PR returns idempotent:true. Requires write auth (set ROADMAPPER_API_KEY). Pass workspaceId to target a workspace other than the env default.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1304,7 +1879,7 @@ const TOOLS = [
       "PREREQUISITE: get_agents_md once this session (enforced). The capability must exist.\n" +
       "ANTI-PATTERN: do not use to declare the FINAL outcome (use outcomeStatus via update_capability for that). Readings are observations along the way, not the verdict.\n" +
       "EXAMPLE: record_outcome_reading({ capabilityId: 'CAP-9F2C7E', value: 0.41, asOf: '2026-05-12', source: 'mixpanel: activated_within_7d weekly', note: 'sample size 4218' })\n\n" +
-      "Requires SUPABASE_SERVICE_ROLE_KEY. Audit log records each reading as 'outcome_reading_recorded'.",
+      "Requires write auth (set ROADMAPPER_API_KEY). Audit log records each reading as 'outcome_reading_recorded'.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1338,6 +1913,38 @@ const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "detect_capability_gaps",
+    description:
+      "Find CLUSTERS of uncategorized tasks that don't fit any existing capability — i.e. work that's accumulating with no quarterly bet to hold it. This is the 'a capability is missing' signal: not 'file this orphan under an existing cap' (that's suggest_capability_for + move_task), but 'these N orphans share a theme that no capability covers — consider proposing one.'\n\n" +
+      "How it works: takes every uncategorized non-archived task, scores its best fit against active capabilities, keeps the ones with no decent fit ('homeless'), then clusters the homeless tasks by shared vocabulary. Each returned cluster has shared keywords, member task ids, and a suggested capability name.\n" +
+      "USE WHEN: triaging a webhook-fed workspace (lots of orphans), at quarterly review, or any time you want to know whether the roadmap is missing a bet. Pair with list_uncategorized_tasks.\n" +
+      "PREREQUISITE: none — read-only. Counts as capability discovery (it enumerates every active capability to score fit), so it satisfies the propose_capability gate.\n" +
+      "ANTI-PATTERN: don't treat a cluster as an automatic mandate to create a capability — capabilities are quarterly bets, a human confirms. A single homeless task is not a gap; that's just an orphan to file. Tune minClusterSize/fitThreshold rather than acting on noise.\n" +
+      "EXAMPLE: detect_capability_gaps({ minClusterSize: 3 })",
+    inputSchema: {
+      type: "object",
+      properties: {
+        minClusterSize: {
+          type: "integer",
+          minimum: 2,
+          maximum: 50,
+          description:
+            "Min homeless tasks sharing a theme to report as a gap. Default 3. A cluster smaller than this is noise, not a missing bet.",
+        },
+        fitThreshold: {
+          type: "number",
+          minimum: 0,
+          maximum: 1,
+          description:
+            "A task is 'homeless' when its best Jaccard fit against any active capability is below this. Default 0.2 (the 'medium' bar). Raise to be stricter about what counts as already-covered.",
+        },
+        includeArchived: { type: "boolean" },
+        workspaceId: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
 /**
@@ -1382,7 +1989,7 @@ function archiveLifecycleTools() {
         "PREREQUISITE: get_agents_md once this session (enforced). For capabilities/themes, every active child must already be archived — the server refuses with a count of blocking children. For tasks, no child check.\n" +
         `ANTI-PATTERN: do not archive a ${kind} you might come back to within the same session — prefer moving it (move_${kind === "theme" ? "capability" : kind}) or updating its status. Archive is the right tool for "this is closed out, get it out of the picker."\n` +
         `EXAMPLE: ${example}\n\n` +
-        "Idempotent: re-archiving an already-archived entity returns { idempotent: true } and emits no audit row. Requires SUPABASE_SERVICE_ROLE_KEY. Pass workspaceId to target a workspace other than the env default.",
+        "Idempotent: re-archiving an already-archived entity returns { idempotent: true } and emits no audit row. Requires write auth (set ROADMAPPER_API_KEY). Pass workspaceId to target a workspace other than the env default.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1408,7 +2015,7 @@ function archiveLifecycleTools() {
         "PREREQUISITE: get_agents_md once this session (enforced). The parent (if any) must be active — cannot unarchive a task whose capability is archived, or a capability whose theme is archived. Unarchive the parent first.\n" +
         "ANTI-PATTERN: do not unarchive en masse without thinking — every unarchive re-floats noise into list views. If you're recovering from an over-aggressive archive sweep, work top-down.\n" +
         `EXAMPLE: un${example.replace("archive", "archive")}\n\n` +
-        "Idempotent: unarchiving an already-active entity returns { idempotent: true }. Requires SUPABASE_SERVICE_ROLE_KEY.",
+        "Idempotent: unarchiving an already-active entity returns { idempotent: true }. Requires write auth (set ROADMAPPER_API_KEY).",
       inputSchema: {
         type: "object",
         properties: {
@@ -1468,7 +2075,7 @@ function moveLifecycleTools() {
         "PREREQUISITE: get_agents_md once this session (enforced). Target parent must exist AND be active — refuses move into an archived parent.\n" +
         `ANTI-PATTERN: do not use move to change anything other than the parent. To rename or rescope, use update_${kind} (coming soon). To delete, use archive_${kind}.\n` +
         `EXAMPLE: ${example}\n\n` +
-        "Idempotent: moving to the current parent returns { idempotent: true } and emits no audit row. Requires SUPABASE_SERVICE_ROLE_KEY.",
+        "Idempotent: moving to the current parent returns { idempotent: true } and emits no audit row. Requires write auth (set ROADMAPPER_API_KEY).",
       inputSchema: {
         type: "object",
         properties: {
@@ -1589,7 +2196,7 @@ function updateLifecycleTools() {
         team: { type: "string" },
         confidence: { type: "number", description: "0–95." },
         impact: { type: "number", description: "One of 0.25, 0.5, 1, 2, 3." },
-        roi: { type: "number" },
+        roi: { type: "number", description: "Estimated annual ROI in raw dollars (e.g. 2500000 = $2.5M)." },
         tags: { type: "array", items: { type: "string" } },
         links: { type: "object", additionalProperties: { type: "string" } },
       },
@@ -1604,7 +2211,7 @@ function updateLifecycleTools() {
         name: { type: "string", description: "Theme name. Minimum 5 chars." },
         description: { type: "string" },
         owner: { type: "string" },
-        targetRoi: { type: "number" },
+        targetRoi: { type: "number", description: "Annual ROI target in raw dollars (e.g. 20000000 = $20M)." },
       },
       example:
         "update_theme({ themeId: 'TH-100042', patch: { name: 'Platform Reliability' }, reason: 'sharper name; same scope' })",
@@ -1627,7 +2234,7 @@ function updateLifecycleTools() {
         `PREREQUISITE: get_agents_md once this session (enforced). Reason required (audit trail). ${reparentHint}\n` +
         `ANTI-PATTERN: do not echo the entity back to the server — pass only the keys that changed. The server diffs against current state and a patch that matches everything returns { idempotent: true }.\n` +
         `EXAMPLE: ${example}\n\n` +
-        "Idempotent: a patch where every key already matches current state returns { idempotent: true } and emits no audit row. Requires SUPABASE_SERVICE_ROLE_KEY.",
+        "Idempotent: a patch where every key already matches current state returns { idempotent: true } and emits no audit row. Requires write auth (set ROADMAPPER_API_KEY).",
     inputSchema: {
       type: "object",
       properties: {
@@ -1682,6 +2289,36 @@ async function callTool(name, args) {
   // read. Tools that need to know the resolved id later (write paths,
   // snapshot) read it back via resolveWorkspaceId(args?.workspaceId).
   const wsId = resolveWorkspaceId(args?.workspaceId);
+
+  // get_active_workspace answers "where am I pointed" without touching
+  // the DB — return before the projection read below. Cheap by design:
+  // agents should be able to spam it to confirm orientation.
+  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.";
+    }
+    return textResult(
+      JSON.stringify(
+        {
+          workspaceId: id,
+          resolvedFrom: source, // "arg" | "snapshot" | "env" | "none"
+          writeMode: writeMode(), // "broker" | "operator" | "read-only"
+          backendConfigured: Boolean(url),
+          ...(note ? { note } : {}),
+        },
+        null,
+        2
+      )
+    );
+  }
+
   // 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).
@@ -1767,28 +2404,62 @@ async function callTool(name, args) {
         "Rank existing capabilities by relevance before proposing a new one. If any score is >0.4, attach tasks there instead."
       );
     }
-    // Cross-workspace guard. If the cwd has a .roadmapper/snapshot.json
-    // naming a workspace, and the call carries an explicit workspaceId
-    // pointing somewhere else, refuse — almost always a mistake. An
-    // operator who really needs to write across workspaces can set
-    // ROADMAPPER_ALLOW_CROSS_WORKSPACE=1 in env to bypass.
-    const snap = snapshotWorkspaceId();
+    // Cross-workspace guard. If the LOCAL context unambiguously names a
+    // workspace — either the repo the agent is in (roots → repo_workspace_map)
+    // or the cwd's .roadmapper/snapshot.json — and the call carries an
+    // explicit workspaceId pointing somewhere else, refuse. Almost always
+    // a mistake. The repo signal beats the snapshot (it's the more specific
+    // "where am I right now"). An operator who really needs to write across
+    // workspaces can set ROADMAPPER_ALLOW_CROSS_WORKSPACE=1 to bypass.
+    // dryRun is non-destructive validation — let it through both the
+    // cross-workspace and seed-workspace guards.
+    const isDryRun = args?.dryRun === true;
+    const localWs = rootWorkspaceId() ?? snapshotWorkspaceId();
+    const localSource = rootWorkspaceId()
+      ? `the repo you're in (${_rootWorkspaceRepo})`
+      : "the cwd's .roadmapper/snapshot.json";
     const argWs = args?.workspaceId;
     if (
-      snap &&
+      localWs &&
       typeof argWs === "string" &&
       argWs.length > 0 &&
-      argWs !== snap &&
+      argWs !== localWs &&
+      !isDryRun &&
       process.env.ROADMAPPER_ALLOW_CROSS_WORKSPACE !== "1"
     ) {
       session.mutatorBlocks += 1;
       recordTelemetry(
         "mutator_blocked_cross_workspace",
-        { tool: name, targetId, cwdWorkspace: snap, argWorkspace: argWs },
+        { tool: name, targetId, localWorkspace: localWs, argWorkspace: argWs },
         wsId
       );
       return errorResult(
-        `Refusing cross-workspace write: cwd's .roadmapper/snapshot.json names workspace "${snap}" but ${name} call targets "${argWs}". Almost always a mistake — drop the workspaceId arg to use the cwd default, or set ROADMAPPER_ALLOW_CROSS_WORKSPACE=1 to override.`
+        `Refusing cross-workspace write: ${localSource} names workspace "${localWs}" but ${name} call targets "${argWs}". Almost always a mistake — drop the workspaceId arg to use the local default, or set ROADMAPPER_ALLOW_CROSS_WORKSPACE=1 to override.`
+      );
+    }
+    // Seed-workspace guard. The cross-workspace guard above only fires
+    // when a snapshot exists to disagree with. The other half of the
+    // wrong-workspace footgun is launching OUTSIDE any configured
+    // checkout: no arg, no snapshot, so wsId falls through to the env
+    // default — and on an unconfigured install that default is the
+    // bundled seed/demo workspace. Writing real planning data there is
+    // almost never intended. Refuse, unless the caller named "default"
+    // explicitly (source "arg") or pointed env/snapshot at it
+    // deliberately (source "snapshot").
+    const { source: wsSource } = resolveWorkspaceWithSource(args?.workspaceId);
+    if (
+      wsId === SEED_WORKSPACE_ID &&
+      wsSource === "env" &&
+      !isDryRun &&
+      // Parity with the cross-workspace guard: operators whose real
+      // workspace is genuinely named "default" (or who otherwise mean
+      // it) can opt out.
+      process.env.ROADMAPPER_ALLOW_SEED_WORKSPACE !== "1"
+    ) {
+      session.mutatorBlocks += 1;
+      recordTelemetry("mutator_blocked_seed_workspace", { tool: name, targetId }, wsId);
+      return errorResult(
+        `Refusing to write to the seed/demo workspace "${SEED_WORKSPACE_ID}": it was resolved from the env default, the call carries no workspaceId, and there's no .roadmapper/snapshot.json in the cwd — so the agent was likely launched outside a configured repo checkout and is about to pollute the placeholder data a fresh install ships with. Run get_active_workspace to confirm where you're pointed. To proceed deliberately, pass workspaceId explicitly, set ROADMAPPER_WORKSPACE_ID to the workspace you mean, or set ROADMAPPER_ALLOW_SEED_WORKSPACE=1.`
       );
     }
     recordTelemetry("mutator_attempted", { tool: name, targetId }, wsId);
@@ -1826,7 +2497,9 @@ async function callTool(name, args) {
       return withReminder(
         "list_capabilities",
         projected,
-        textResult(JSON.stringify(filtered, null, 2))
+        compactResult(
+          paginateRows(filtered, args, capabilityLight, projected.tasks)
+        )
       );
     }
     case "list_tasks": {
@@ -1841,7 +2514,25 @@ async function callTool(name, args) {
       return withReminder(
         "list_tasks",
         projected,
-        textResult(JSON.stringify(filtered, null, 2))
+        compactResult(paginateRows(filtered, args, taskLight))
+      );
+    }
+    case "list_uncategorized_tasks": {
+      // capabilityId == null catches both an explicit null and a
+      // stripped-undefined key (unparented PRs auto-created by the
+      // webhook with no Roadmapper-Capability trailer + no Jaccard
+      // hit). A task may still carry a pillarId (direct theme
+      // parenting); we only key on the capability link here.
+      let filtered = projected.tasks.filter((t) => t.capabilityId == null);
+      if (args?.status)
+        filtered = filtered.filter((t) => t.status === args.status);
+      if (!args?.includeArchived) {
+        filtered = filtered.filter((t) => !t.archived);
+      }
+      return withReminder(
+        "list_uncategorized_tasks",
+        projected,
+        compactResult(paginateRows(filtered, args, taskLight))
       );
     }
     case "get_task": {
@@ -1875,10 +2566,17 @@ async function callTool(name, args) {
       const ts = Date.now();
       session.themesListedAt = ts;
       session.capsDiscoveredAt = ts;
+      const { source } = resolveWorkspaceWithSource(args?.workspaceId);
       return withReminder(
         "get_roadmap_snapshot",
         projected,
-        getRoadmapSnapshot(projected, wsId, args?.includeArchived === true)
+        getRoadmapSnapshot(
+          projected,
+          wsId,
+          args?.includeArchived === true,
+          source,
+          args?.detail === true
+        )
       );
     }
     case "propose_task":
@@ -1940,6 +2638,12 @@ async function callTool(name, args) {
       return recordOutcomeReading(args, wsId, projected);
     case "list_stale_outcomes":
       return listStaleOutcomes(args, projected);
+    case "detect_capability_gaps":
+      // Enumerates every active capability to score fit, so the agent
+      // has effectively discovered the catalogue — satisfies the
+      // propose_capability gate (the natural next step on a gap).
+      session.capsDiscoveredAt = Date.now();
+      return detectCapabilityGaps(args, projected);
     default:
       return errorResult(`Unknown tool: ${name}`);
   }
@@ -1976,6 +2680,61 @@ async function proposeTask(args, projected, wsId) {
   )
     return errorResult(`expectedScope must be a positive number, got ${args.expectedScope}.`);
 
+  // Warn-on-skip (not block): if the agent never surveyed capabilities
+  // this session, it may have picked the wrong parent. Rather than a
+  // hard gate (which would false-positive on legit known-capability
+  // filing and just get worked around), we compute a fit check and
+  // attach an actionable _meta warning to the response. propose_task
+  // stays allow; propose_capability keeps its hard discovery gate.
+  //
+  // Useful signal: score the task text against the CHOSEN capability
+  // and against the best available one. If a different capability
+  // scores materially higher, surface it — that's the likely-misfiled
+  // case, the exact thing discovery would have caught.
+  function buildSkipWarning() {
+    if (session.capsDiscoveredAt !== null) return null; // discovery happened
+    const taskToks = tokenize(
+      [args.title ?? "", args.summary ?? ""].join(" ")
+    );
+    if (taskToks.size === 0) return null;
+    const themeById = new Map(
+      (projected.themes ?? []).map((t) => [t.id, t])
+    );
+    const hayFor = (c) => {
+      const theme = themeById.get(c.pillarId);
+      const titles = (projected.tasks ?? [])
+        .filter((t) => t.capabilityId === c.id)
+        .map((t) => t.title)
+        .join(" ");
+      return tokenize(
+        [c.name, c.description ?? "", c.outcome ?? "", theme?.name ?? "", titles].join(" ")
+      );
+    };
+    const chosenScore = jaccardScore(taskToks, hayFor(cap));
+    // Best OTHER active, non-delivered capability.
+    let best = null;
+    for (const c of projected.capabilities) {
+      if (c.id === cap.id || c.archived) continue;
+      if (effectiveCapabilityStatus(c, projected.tasks) === "delivered") continue;
+      const s = jaccardScore(taskToks, hayFor(c));
+      if (!best || s > best.score) best = { id: c.id, name: c.name, score: s };
+    }
+    const base =
+      "Heads up: you filed this task without calling suggest_capability_for / list_capabilities / get_roadmap_snapshot this session, so you may not have surveyed existing capabilities. ";
+    // Only escalate to a concrete suggestion when another cap clearly
+    // fits better than the chosen one — otherwise just a gentle note.
+    if (best && best.score > 0.2 && best.score > chosenScore + 0.1) {
+      return (
+        base +
+        `The task text fits ${best.id} (${best.name}) noticeably better (score ${best.score.toFixed(2)}) than the chosen ${cap.id} (${chosenScore.toFixed(2)}). If that's the right home, move_task it there.`
+      );
+    }
+    return (
+      base +
+      "If you're confident in the parent, ignore this; otherwise call suggest_capability_for({ taskId }) to confirm."
+    );
+  }
+
   const effort = args.effort;
   const start = todayISO();
   // Target dates are day-resolution; round up so sub-day estimates
@@ -2012,6 +2771,11 @@ async function proposeTask(args, projected, wsId) {
     ...(args.expectedScope !== undefined ? { expectedScope: args.expectedScope } : {}),
   };
 
+  const skipWarning = buildSkipWarning();
+  const skipMeta = skipWarning
+    ? { _meta: { roadmapper: { reminder: skipWarning } } }
+    : undefined;
+
   if (args.dryRun) {
     return textResult(
       JSON.stringify(
@@ -2019,12 +2783,13 @@ async function proposeTask(args, projected, wsId) {
           ok: true,
           dryRun: true,
           wouldCreate: task,
-          warnings: [],
+          warnings: skipWarning ? [skipWarning] : [],
           message: `Would create task ${id} under ${cap.id} (${cap.name}). No record written.`,
         },
         null,
         2
-      )
+      ),
+      skipMeta
     );
   }
 
@@ -2055,13 +2820,15 @@ async function proposeTask(args, projected, wsId) {
         id: stored.id,
         capabilityId: stored.capabilityId,
         idempotent,
+        ...(skipWarning ? { warnings: [skipWarning] } : {}),
         message: idempotent
           ? `Task ${stored.id} already exists with idempotencyKey ${args.idempotencyKey}; returning existing task instead of creating a duplicate.`
           : `Created ${stored.id} under ${cap.id} (${cap.name}). status=planned, authorKind=agent.`,
       },
       null,
       2
-    )
+    ),
+    skipMeta
   );
 }
 
@@ -2233,7 +3000,13 @@ async function proposeCapability(args, projected, wsId) {
  * passes that id back on `propose_task` / `propose_capability` /
  * `propose_theme` calls.
  */
-function getRoadmapSnapshot(projected, wsId, includeArchived = false) {
+function getRoadmapSnapshot(
+  projected,
+  wsId,
+  includeArchived = false,
+  source,
+  detail = false
+) {
   // Archived entities are filtered out by default — the snapshot
   // is meant to surface what an agent should plan against, and
   // archived rows are by definition not in scope. Pass
@@ -2250,31 +3023,67 @@ function getRoadmapSnapshot(projected, wsId, includeArchived = false) {
     if (!includeArchived && t.archived) return false;
     return t.status === "in_progress" || t.status === "planned";
   });
-  return textResult(
-    JSON.stringify(
-      {
-        workspaceId: wsId,
-        generatedAt: new Date().toISOString(),
-        themes,
-        capabilities: activeCapabilities,
-        tasks: inFlightTasks,
-        counts: {
-          themes: themes.length,
-          activeCapabilities: activeCapabilities.length,
-          inFlightTasks: inFlightTasks.length,
-          totalCapabilities: projected.capabilities.length,
-          totalTasks: projected.tasks.length,
-        },
-      },
-      null,
-      2
-    )
-  );
+
+  // Light by default — this is the cold-start orient call, so it must
+  // never blow the token budget on a large workspace (the 670-task
+  // workspace produced an 81KB full-detail response). detail:true
+  // restores full rows. Even light, we cap the task list: counts
+  // below carries the true totals, and an agent that needs every row
+  // should use list_tasks with a filter, not the snapshot.
+  const capItems = detail
+    ? activeCapabilities
+    : activeCapabilities.map((c) => capabilityLight(c, projected.tasks));
+  const taskCap = detail ? LIST_MAX_LIMIT : LIST_DEFAULT_LIMIT;
+  const taskSlice = inFlightTasks.slice(0, taskCap);
+  const taskItems = detail ? taskSlice : taskSlice.map(taskLight);
+
+  return compactResult({
+    workspaceId: wsId,
+    // How wsId was resolved (arg / snapshot / env / none). Lets the
+    // agent catch a silent env-default fall-through before planning
+    // against the wrong (often seed) workspace. Omitted when unknown.
+    ...(source ? { resolvedFrom: source } : {}),
+    generatedAt: new Date().toISOString(),
+    mode: detail ? "detail" : "summary",
+    themes,
+    capabilities: capItems,
+    tasks: taskItems,
+    tasksTruncated: inFlightTasks.length > taskSlice.length,
+    counts: {
+      themes: themes.length,
+      activeCapabilities: activeCapabilities.length,
+      inFlightTasks: inFlightTasks.length,
+      totalCapabilities: projected.capabilities.length,
+      totalTasks: projected.tasks.length,
+    },
+  });
 }
 
 function suggestCapabilityFor(args, projected) {
-  const desc = (args.description || "").trim();
-  if (!desc) return errorResult("description is required.");
+  // Two query sources: free-text description, or an existing task
+  // (title + summary). taskId is the triage path — rank a home for
+  // an orphan surfaced by list_uncategorized_tasks. Exactly one.
+  if (args.taskId && args.description) {
+    return errorResult(
+      "Pass exactly one of description / taskId, not both."
+    );
+  }
+  let desc;
+  let sourceTaskId;
+  if (args.taskId) {
+    const task = projected.tasks.find((t) => t.id === args.taskId);
+    if (!task) return errorResult(`Task ${args.taskId} not found.`);
+    sourceTaskId = task.id;
+    desc = [task.title ?? "", task.summary ?? ""].join(" ").trim();
+    if (!desc) {
+      return errorResult(
+        `Task ${args.taskId} has no title or summary to match on.`
+      );
+    }
+  } else {
+    desc = (args.description || "").trim();
+    if (!desc) return errorResult("description or taskId is required.");
+  }
   const limit = Math.min(25, Math.max(1, args.limit ?? 5));
 
   // Skip delivered capabilities — they're closed bets. A new PR
@@ -2347,6 +3156,7 @@ function suggestCapabilityFor(args, projected) {
       {
         ok: true,
         query: desc,
+        ...(sourceTaskId ? { taskId: sourceTaskId } : {}),
         matches: ranked,
         hint:
           ranked.length === 0
@@ -2931,6 +3741,162 @@ function listStaleOutcomes(args, projected) {
   );
 }
 
+/**
+ * Find clusters of uncategorized tasks that no existing capability
+ * covers — the "a bet is missing" signal. Two-stage:
+ *   1. Homeless filter: a task is homeless when its BEST Jaccard fit
+ *      against any active (non-delivered) capability is below
+ *      fitThreshold. Tasks that fit an existing cap aren't gaps —
+ *      they're just orphans to file (suggest_capability_for +
+ *      move_task), so they're excluded here.
+ *   2. Greedy clustering: seed a cluster from the first ungrouped
+ *      homeless task, then pull in any other homeless task whose
+ *      tokens overlap the cluster's accumulated tokens at >=
+ *      fitThreshold. Repeat until everything is grouped. Clusters
+ *      below minClusterSize are dropped as noise.
+ *
+ * Read-only, deterministic (no Date/random), and order-stable so a
+ * resumed/cached run reproduces. Returns a suggested capability name
+ * per cluster (its top shared keywords) — a HINT for propose_capability,
+ * not an auto-create.
+ */
+function detectCapabilityGaps(args, projected) {
+  // Guard against non-numeric input (a non-compliant client, or an
+  // explicit null) — Math.floor(NaN) would propagate NaN through the
+  // clamp and make `members.length >= NaN` always false, silently
+  // returning zero gaps. Fall back to the default unless we got a
+  // finite number, mirroring the fitThreshold guard below.
+  const minClusterSize =
+    typeof args?.minClusterSize === "number" &&
+    Number.isFinite(args.minClusterSize)
+      ? Math.min(50, Math.max(2, Math.floor(args.minClusterSize)))
+      : 3;
+  const fitThreshold =
+    typeof args?.fitThreshold === "number" &&
+    Number.isFinite(args.fitThreshold)
+      ? Math.min(1, Math.max(0, args.fitThreshold))
+      : 0.2;
+  const includeArchived = args?.includeArchived === true;
+
+  // Active capabilities = candidate homes. Build each one's haystack
+  // once (same vocabulary blend suggest_capability_for uses).
+  const themeById = new Map((projected.themes ?? []).map((t) => [t.id, t]));
+  const activeCaps = projected.capabilities.filter(
+    (c) =>
+      (includeArchived || !c.archived) &&
+      effectiveCapabilityStatus(c, projected.tasks) !== "delivered"
+  );
+  const capHaystacks = activeCaps.map((c) => {
+    const theme = themeById.get(c.pillarId);
+    const taskTitles = (projected.tasks ?? [])
+      .filter((t) => t.capabilityId === c.id)
+      .map((t) => t.title)
+      .join(" ");
+    return tokenize(
+      [
+        c.name,
+        c.description ?? "",
+        c.outcome ?? "",
+        theme?.name ?? "",
+        theme?.description ?? "",
+        taskTitles,
+      ].join(" ")
+    );
+  });
+
+  // Stage 1 — homeless uncategorized tasks (best cap fit < threshold).
+  const uncategorized = projected.tasks.filter(
+    (t) => t.capabilityId == null && (includeArchived || !t.archived)
+  );
+  const homeless = [];
+  for (const t of uncategorized) {
+    const toks = tokenize([t.title ?? "", t.summary ?? ""].join(" "));
+    if (toks.size === 0) continue; // nothing to match on
+    let best = 0;
+    for (const hay of capHaystacks) {
+      const s = jaccardScore(toks, hay);
+      if (s > best) best = s;
+    }
+    if (best < fitThreshold) homeless.push({ task: t, toks, bestFit: best });
+  }
+
+  // Stage 2 — greedy clustering by shared vocabulary. Deterministic:
+  // iterate in array order, never random.
+  const used = new Set();
+  const clusters = [];
+  for (let i = 0; i < homeless.length; i++) {
+    if (used.has(i)) continue;
+    used.add(i);
+    const members = [homeless[i]];
+    const clusterToks = new Set(homeless[i].toks);
+    for (let j = i + 1; j < homeless.length; j++) {
+      if (used.has(j)) continue;
+      if (jaccardScore(homeless[j].toks, clusterToks) >= fitThreshold) {
+        used.add(j);
+        members.push(homeless[j]);
+        for (const tk of homeless[j].toks) clusterToks.add(tk);
+      }
+    }
+    if (members.length >= minClusterSize) clusters.push({ members, clusterToks });
+  }
+
+  // Shape the output: shared keywords (most common tokens across the
+  // cluster's members), a suggested name, and member task ids/titles.
+  const shaped = clusters
+    .map(({ members, clusterToks }) => {
+      // Rank tokens by how many members contain them — the shared
+      // vocabulary is what names the bet.
+      const freq = new Map();
+      for (const m of members)
+        for (const tk of m.toks) freq.set(tk, (freq.get(tk) ?? 0) + 1);
+      const keywords = [...freq.entries()]
+        .filter(([, n]) => n >= 2) // shared by at least two members
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 6)
+        .map(([tk]) => tk);
+      return {
+        size: members.length,
+        keywords,
+        suggestedCapabilityName:
+          keywords.length > 0
+            ? keywords.slice(0, 4).join(" ")
+            : "(no shared keywords)",
+        tasks: members.map((m) => ({
+          id: m.task.id,
+          title: m.task.title,
+          bestExistingFit: Number(m.bestFit.toFixed(3)),
+        })),
+      };
+    })
+    .sort((a, b) => b.size - a.size);
+
+  const meta =
+    shaped.length > 0
+      ? {
+          _meta: {
+            roadmapper: {
+              reminder:
+                `${shaped.length} capability gap(s) detected — clusters of uncategorized work no existing bet covers. ` +
+                "Each is a CANDIDATE for propose_capability (confirm with the user — capabilities are quarterly bets, not auto-created), then move_tasks the members under it.",
+            },
+          },
+        }
+      : undefined;
+
+  // Compact JSON + optional _meta nudge (textResult spreads `extra`).
+  return textResult(
+    JSON.stringify({
+      uncategorizedScanned: uncategorized.length,
+      homelessCount: homeless.length,
+      minClusterSize,
+      fitThreshold,
+      gapCount: shaped.length,
+      gaps: shaped,
+    }),
+    meta
+  );
+}
+
 async function submitAcceptanceGrades(args, projected, wsId) {
   const task = projected.tasks.find((t) => t.id === args.taskId);
   if (!task) return errorResult(`Task ${args.taskId} not found.`);
@@ -3098,15 +4064,15 @@ async function readResource(uri) {
     // the model," not "this specific call shape ran."
     if (session.rubricFetchedAt === null) {
       session.rubricFetchedAt = Date.now();
-      // Pass the cwd snapshot's workspace id so the row is
-      // visible in Settings → MCP activity. Without this the
-      // resource-route fetch lands with workspace_id=NULL and
-      // gets filtered out for non-operator viewers (per migration
-      // 0038's NULL-workspace lock).
+      // Pass the resolved workspace id (repo → snapshot → env) so the
+      // row is visible in Settings → MCP activity under the right
+      // workspace. Without this the resource-route fetch lands with
+      // workspace_id=NULL and gets filtered out for non-operator
+      // viewers (per migration 0038's NULL-workspace lock).
       recordTelemetry(
         "rubric_fetched",
         { via: "resource" },
-        snapshotWorkspaceId() ?? undefined
+        resolveWorkspaceId() ?? undefined
       );
     }
     return {
@@ -3135,12 +4101,22 @@ async function readResource(uri) {
     const active = projected.capabilities.filter(
       (c) => effectiveCapabilityStatus(c, projected.tasks) !== "delivered"
     );
+    // Resources auto-fire on client connect with NO args and no model
+    // gate — so they MUST be bounded unconditionally. Light rows +
+    // cap, with a total/truncated envelope. An agent that needs full
+    // detail uses list_capabilities({ detail:true }).
+    const capped = active.slice(0, LIST_MAX_LIMIT);
     return {
       contents: [
         {
           uri,
           mimeType: "application/json",
-          text: JSON.stringify(active, null, 2),
+          text: JSON.stringify({
+            total: active.length,
+            returned: capped.length,
+            truncated: active.length > capped.length,
+            items: capped.map((c) => capabilityLight(c, projected.tasks)),
+          }),
         },
       ],
     };
@@ -3149,12 +4125,20 @@ async function readResource(uri) {
     const open = projected.tasks.filter(
       (t) => t.status === "in_progress" || t.status === "planned"
     );
+    // Same rationale as the capabilities resource — bounded + light,
+    // because this fires on connect without anyone asking.
+    const capped = open.slice(0, LIST_MAX_LIMIT);
     return {
       contents: [
         {
           uri,
           mimeType: "application/json",
-          text: JSON.stringify(open, null, 2),
+          text: JSON.stringify({
+            total: open.length,
+            returned: capped.length,
+            truncated: open.length > capped.length,
+            items: capped.map(taskLight),
+          }),
         },
       ],
     };
@@ -3245,6 +4229,11 @@ async function handle(request) {
   const { id, method, params } = request;
   try {
     if (method === "initialize") {
+      // If the client declares roots support, request the root list
+      // right after we respond (can't send mid-handler — the client
+      // isn't listening until it gets our initialize result). The
+      // main loop fires requestClientRoots() once this returns.
+      _clientSupportsRoots = !!params?.capabilities?.roots;
       // Snapshot counts so an MCP client showing server info
       // surfaces actual roadmap shape, not just "connected".
       const projected =
@@ -3279,14 +4268,34 @@ async function handle(request) {
             name: SERVER_NAME,
             version: SERVER_VERSION,
             stats,
-            instructions:
-              "Roadmapper online — " +
-              `${stats.themes} theme${stats.themes === 1 ? "" : "s"}, ` +
-              `${stats.capabilities} capabilit${stats.capabilities === 1 ? "y" : "ies"}, ` +
-              `${stats.openTasks} open task${stats.openTasks === 1 ? "" : "s"}. ` +
-              "Call get_agents_md before planning — the propose_* and submit_acceptance_grades tools refuse without it. " +
-              "Use suggest_capability_for before propose_capability. " +
-              "Slash-prompts available: roadmapper:plan-feature, roadmapper:close-task, roadmapper:weekly-review.",
+            instructions: (() => {
+              // Name the workspace we resolve to RIGHT NOW + where it came
+              // from, so the agent can trust where its writes land instead
+              // of discovering an empty/wrong workspace later. Repo-based
+              // resolution (roots → repo_workspace_map) finishes just after
+              // this handshake, so if the client supports roots we say the
+              // target may refine and to confirm via get_active_workspace.
+              const { id: ws, source } = resolveWorkspaceWithSource();
+              const wsLine = ws
+                ? `Workspace: ${ws} (resolved from ${source}). `
+                : "No workspace resolved yet. ";
+              const rootsLine = _clientSupportsRoots
+                ? "Detecting the repo you're in to pick its workspace; call get_active_workspace before your first write to confirm. "
+                : ws
+                  ? ""
+                  : "Set ROADMAPPER_WORKSPACE_ID or open a connected repo. ";
+              return (
+                "Roadmapper online — " +
+                wsLine +
+                `${stats.themes} theme${stats.themes === 1 ? "" : "s"}, ` +
+                `${stats.capabilities} capabilit${stats.capabilities === 1 ? "y" : "ies"}, ` +
+                `${stats.openTasks} open task${stats.openTasks === 1 ? "" : "s"}. ` +
+                rootsLine +
+                "Call get_agents_md before planning — the propose_* and submit_acceptance_grades tools refuse without it. " +
+                "Use suggest_capability_for before propose_capability. " +
+                "Slash-prompts available: roadmapper:plan-feature, roadmapper:close-task, roadmapper:weekly-review."
+              );
+            })(),
           },
         },
       };
@@ -3324,6 +4333,11 @@ async function handle(request) {
       const result = renderPrompt(params?.name, params?.arguments ?? {});
       return { jsonrpc: "2.0", id, result };
     }
+    if (method === "notifications/roots/list_changed") {
+      // The client's open folders changed — re-pull and re-resolve.
+      requestClientRoots();
+      return null;
+    }
     // Notifications (no id) and unknown methods: ignore.
     if (id === undefined) return null;
     return {
@@ -3516,6 +4530,27 @@ async function runSelftest() {
       pass: (r) =>
         Array.isArray(r?.result?.tools) && r.result.tools.length === TOOLS.length,
     },
+    {
+      name: "get_active_workspace reports a resolution source",
+      fn: () =>
+        handle({
+          id: 22,
+          method: "tools/call",
+          params: { name: "get_active_workspace", arguments: {} },
+        }),
+      pass: (r) => {
+        try {
+          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)
+          );
+        } catch {
+          return false;
+        }
+      },
+    },
     {
       name: "list_themes",
       fn: () =>
@@ -3640,6 +4675,93 @@ async function runSelftest() {
           ? r?.result && !r.result.isError
           : r?.result?.isError === true,
     },
+    {
+      name: "propose_task (warn-on-skip: dryRun WITHOUT discovery attaches a capability-fit warning)",
+      fn: async () => {
+        // Fresh session + rubric (mutator gate) but NO capability
+        // discovery → the warn-on-skip path should fire. dryRun avoids
+        // needing write auth and returns before the RPC.
+        resetSession();
+        await handle({
+          id: 300,
+          method: "tools/call",
+          params: { name: "get_agents_md", arguments: {} },
+        });
+        return handle({
+          id: 301,
+          method: "tools/call",
+          params: {
+            name: "propose_task",
+            arguments: {
+              capabilityId: aCap,
+              title: "Selftest warn task",
+              effort: "S",
+              dryRun: true,
+            },
+          },
+        });
+      },
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        let body;
+        try {
+          body = JSON.parse(r?.result?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        // Warning present in both the warnings[] array and the _meta nudge.
+        return (
+          Array.isArray(body?.warnings) &&
+          body.warnings.length === 1 &&
+          typeof r?.result?._meta?.roadmapper?.reminder === "string"
+        );
+      },
+    },
+    {
+      name: "propose_task (warn-on-skip: dryRun AFTER discovery has NO warning)",
+      fn: async () => {
+        resetSession();
+        await handle({
+          id: 310,
+          method: "tools/call",
+          params: { name: "get_agents_md", arguments: {} },
+        });
+        // get_roadmap_snapshot sets capsDiscoveredAt → discovery done.
+        await handle({
+          id: 311,
+          method: "tools/call",
+          params: { name: "get_roadmap_snapshot", arguments: {} },
+        });
+        return handle({
+          id: 312,
+          method: "tools/call",
+          params: {
+            name: "propose_task",
+            arguments: {
+              capabilityId: aCap,
+              title: "Selftest no-warn task",
+              effort: "S",
+              dryRun: true,
+            },
+          },
+        });
+      },
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        let body;
+        try {
+          body = JSON.parse(r?.result?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        // Discovery happened → warnings empty, no _meta nudge.
+        return (
+          Array.isArray(body?.warnings) &&
+          body.warnings.length === 0 &&
+          !r?.result?._meta?.roadmapper?.reminder
+        );
+      },
+    },
     {
       name: "propose_theme (missing name returns error result)",
       fn: () =>
@@ -3819,6 +4941,398 @@ async function runSelftest() {
         }),
       pass: (r) => r?.result?.isError === true,
     },
+    {
+      name: "suggest_capability_for (taskId path builds query from the task + echoes taskId)",
+      fn: () =>
+        handle({
+          id: 201,
+          method: "tools/call",
+          params: {
+            name: "suggest_capability_for",
+            arguments: { taskId: "TK-DEMO" },
+          },
+        }),
+      pass: (r) =>
+        !r?.result?.isError &&
+        r?.result?.content?.[0]?.text?.includes('"matches"') &&
+        r?.result?.content?.[0]?.text?.includes('"taskId": "TK-DEMO"'),
+    },
+    {
+      name: "suggest_capability_for (unknown taskId rejected)",
+      fn: () =>
+        handle({
+          id: 202,
+          method: "tools/call",
+          params: {
+            name: "suggest_capability_for",
+            arguments: { taskId: "TK-000000" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "suggest_capability_for (description + taskId together rejected)",
+      fn: () =>
+        handle({
+          id: 203,
+          method: "tools/call",
+          params: {
+            name: "suggest_capability_for",
+            arguments: { taskId: "TK-DEMO", description: "x" },
+          },
+        }),
+      pass: (r) => r?.result?.isError === true,
+    },
+    {
+      name: "list_uncategorized_tasks (envelope shape, excludes parented seed task)",
+      fn: () =>
+        handle({
+          id: 204,
+          method: "tools/call",
+          params: {
+            name: "list_uncategorized_tasks",
+            arguments: {},
+          },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        const text = r?.result?.content?.[0]?.text;
+        if (typeof text !== "string") return false;
+        let env;
+        try {
+          env = JSON.parse(text);
+        } catch {
+          return false;
+        }
+        // New shape: { total, returned, truncated, items }. The seed's
+        // only task (TK-DEMO) is parented under CAP-DEMO, so it must
+        // NOT appear in the uncategorized items.
+        return (
+          Array.isArray(env?.items) &&
+          typeof env.total === "number" &&
+          typeof env.truncated === "boolean" &&
+          !env.items.some((t) => t.id === "TK-DEMO")
+        );
+      },
+    },
+    {
+      name: "list_tasks (default: envelope + LIGHT rows drop prs/acceptance/summary)",
+      fn: () =>
+        handle({
+          id: 205,
+          method: "tools/call",
+          params: { name: "list_tasks", arguments: {} },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        let env;
+        try {
+          env = JSON.parse(r?.result?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        if (!Array.isArray(env?.items)) return false;
+        // Light rows must NOT carry the heavy arrays/text. (Seed has
+        // at least TK-DEMO.) Every returned row is light.
+        return env.items.every(
+          (t) =>
+            !("prs" in t) &&
+            !("acceptance" in t) &&
+            !("acceptanceGrades" in t) &&
+            !("summary" in t) &&
+            "id" in t &&
+            "status" in t
+        );
+      },
+    },
+    {
+      name: "list_tasks (detail:true restores full rows)",
+      fn: () =>
+        handle({
+          id: 206,
+          method: "tools/call",
+          params: { name: "list_tasks", arguments: { detail: true } },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        let env;
+        try {
+          env = JSON.parse(r?.result?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        // TK-DEMO in the seed carries acceptance criteria; detail mode
+        // must surface them. Find it and confirm a heavy field is back.
+        const demo = env?.items?.find((t) => t.id === "TK-DEMO");
+        return !!demo && "acceptance" in demo;
+      },
+    },
+    {
+      name: "list_tasks (limit clamps to the requested cap)",
+      fn: () =>
+        handle({
+          id: 207,
+          method: "tools/call",
+          params: { name: "list_tasks", arguments: { limit: 1 } },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        let env;
+        try {
+          env = JSON.parse(r?.result?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        return (
+          Array.isArray(env?.items) &&
+          env.items.length <= 1 &&
+          env.returned <= 1
+        );
+      },
+    },
+    {
+      name: "list_capabilities (light row carries EFFECTIVE status, not the null column)",
+      fn: () =>
+        handle({
+          id: 210,
+          method: "tools/call",
+          params: { name: "list_capabilities", arguments: {} },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        let env;
+        try {
+          env = JSON.parse(r?.result?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        // CAP-DEMO has no explicit status column; its child task
+        // TK-DEMO is 'planned', so the effective status must derive to
+        // a non-empty value in the light row (regression guard: before
+        // the fix, status was stripped and absent entirely).
+        const demo = env?.items?.find((c) => c.id === "CAP-DEMO");
+        return !!demo && typeof demo.status === "string" && demo.status.length > 0;
+      },
+    },
+    {
+      name: "list_capabilities (compact JSON — no pretty-print whitespace)",
+      fn: () =>
+        handle({
+          id: 208,
+          method: "tools/call",
+          params: { name: "list_capabilities", arguments: {} },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        const text = r?.result?.content?.[0]?.text;
+        if (typeof text !== "string") return false;
+        // Pretty-print would emit '\n      ' indentation. Compact must
+        // not. Also confirm it parses to the envelope shape.
+        if (/\n\s\s/.test(text)) return false;
+        let env;
+        try {
+          env = JSON.parse(text);
+        } catch {
+          return false;
+        }
+        return Array.isArray(env?.items) && typeof env.total === "number";
+      },
+    },
+    {
+      name: "get_roadmap_snapshot (summary mode by default: light tasks + counts + mode flag)",
+      fn: () =>
+        handle({
+          id: 209,
+          method: "tools/call",
+          params: { name: "get_roadmap_snapshot", arguments: {} },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        let snap;
+        try {
+          snap = JSON.parse(r?.result?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        if (snap?.mode !== "summary") return false;
+        if (!snap?.counts || typeof snap.counts.totalTasks !== "number")
+          return false;
+        // Light tasks in summary mode: no heavy arrays.
+        return (snap.tasks ?? []).every(
+          (t) => !("prs" in t) && !("acceptance" in t)
+        );
+      },
+    },
+    {
+      name: "detect_capability_gaps (through handle: seed has no orphans → well-formed empty result)",
+      fn: () =>
+        handle({
+          id: 211,
+          method: "tools/call",
+          params: { name: "detect_capability_gaps", arguments: {} },
+        }),
+      pass: (r) => {
+        if (r?.result?.isError) return false;
+        let out;
+        try {
+          out = JSON.parse(r?.result?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        // Seed's only task is categorized → zero homeless, zero gaps,
+        // but the envelope fields must all be present and numeric.
+        return (
+          Array.isArray(out?.gaps) &&
+          out.gapCount === 0 &&
+          typeof out.uncategorizedScanned === "number" &&
+          typeof out.homelessCount === "number"
+        );
+      },
+    },
+    {
+      name: "detect_capability_gaps (direct: clusters homeless tasks, names the cluster by shared keywords)",
+      fn: () => {
+        // Fixture: one active capability about 'billing invoices', plus
+        // 4 uncategorized tasks — 3 clearly about 'wallet apple google
+        // pass' (a missing bet) and 1 lone 'documentation typo'.
+        const projected = {
+          themes: [{ id: "TH-1", name: "Platform", description: "" }],
+          capabilities: [
+            {
+              id: "CAP-BILL",
+              pillarId: "TH-1",
+              name: "Billing invoices",
+              description: "invoice generation and billing runs",
+              outcome: "invoices delivered",
+              status: "in_progress",
+            },
+          ],
+          tasks: [
+            { id: "TK-1", capabilityId: null, title: "wallet apple pass provisioning", summary: "google wallet pass signing" },
+            { id: "TK-2", capabilityId: null, title: "google wallet pass install telemetry", summary: "apple wallet pass rate" },
+            { id: "TK-3", capabilityId: null, title: "apple google wallet pass dashboard", summary: "wallet pass provisioning ui" },
+            { id: "TK-4", capabilityId: null, title: "fix documentation typo", summary: "" },
+          ],
+        };
+        return detectCapabilityGaps({ minClusterSize: 3 }, projected);
+      },
+      pass: (r) => {
+        if (r?.isError) return false;
+        let out;
+        try {
+          out = JSON.parse(r?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        // The 3 wallet-pass tasks cluster; the lone typo task does not
+        // reach minClusterSize=3. So exactly one gap of size 3, named
+        // from the shared 'wallet/pass' vocabulary.
+        if (out.gapCount !== 1) return false;
+        const gap = out.gaps[0];
+        return (
+          gap.size === 3 &&
+          gap.keywords.includes("wallet") &&
+          gap.keywords.includes("pass") &&
+          !gap.tasks.some((t) => t.id === "TK-4")
+        );
+      },
+    },
+    {
+      name: "detect_capability_gaps (direct: tasks that FIT an existing cap are not homeless)",
+      fn: () => {
+        // 3 tasks that clearly match the billing capability — they must
+        // NOT be reported as a gap (they have a home; they just need
+        // filing via move_task, not a new capability).
+        const projected = {
+          themes: [{ id: "TH-1", name: "Platform", description: "" }],
+          capabilities: [
+            {
+              id: "CAP-BILL",
+              pillarId: "TH-1",
+              name: "Billing invoices generation",
+              description: "invoice generation billing runs dunning",
+              outcome: "invoices delivered to every customer",
+              status: "in_progress",
+            },
+          ],
+          tasks: [
+            { id: "TK-1", capabilityId: null, title: "billing invoice generation bug", summary: "invoice runs" },
+            { id: "TK-2", capabilityId: null, title: "invoice generation dunning", summary: "billing runs" },
+            { id: "TK-3", capabilityId: null, title: "billing invoice dunning runs", summary: "invoice generation" },
+          ],
+        };
+        return detectCapabilityGaps({ minClusterSize: 2 }, projected);
+      },
+      pass: (r) => {
+        if (r?.isError) return false;
+        let out;
+        try {
+          out = JSON.parse(r?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        // They fit CAP-BILL, so zero homeless → zero gaps.
+        return out.gapCount === 0 && out.homelessCount === 0;
+      },
+    },
+    {
+      name: "detect_capability_gaps (direct: minClusterSize filters clusters below the floor)",
+      fn: () => {
+        const projected = {
+          themes: [{ id: "TH-1", name: "Platform", description: "" }],
+          capabilities: [],
+          tasks: [
+            { id: "TK-1", capabilityId: null, title: "wallet apple pass", summary: "google wallet" },
+            { id: "TK-2", capabilityId: null, title: "google wallet pass", summary: "apple wallet" },
+          ],
+        };
+        // Two homeless tasks cluster, but minClusterSize=3 drops it.
+        return detectCapabilityGaps({ minClusterSize: 3 }, projected);
+      },
+      pass: (r) => {
+        if (r?.isError) return false;
+        let out;
+        try {
+          out = JSON.parse(r?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        return out.homelessCount === 2 && out.gapCount === 0;
+      },
+    },
+    {
+      name: "detect_capability_gaps (regression: non-numeric minClusterSize falls back to default, not NaN)",
+      fn: () => {
+        // 3 wallet-pass tasks that SHOULD cluster into a gap at the
+        // default minClusterSize=3. Pass a non-numeric minClusterSize
+        // (a non-compliant client / explicit null). Before the guard,
+        // Math.floor(NaN) propagated → members.length >= NaN always
+        // false → zero gaps (silent wrong answer). After: falls back to
+        // default 3, so the gap is still detected.
+        const projected = {
+          themes: [{ id: "TH-1", name: "Platform", description: "" }],
+          capabilities: [],
+          tasks: [
+            { id: "TK-1", capabilityId: null, title: "wallet apple pass provisioning", summary: "google wallet pass" },
+            { id: "TK-2", capabilityId: null, title: "google wallet pass telemetry", summary: "apple wallet pass" },
+            { id: "TK-3", capabilityId: null, title: "apple google wallet pass dashboard", summary: "wallet pass" },
+          ],
+        };
+        return detectCapabilityGaps({ minClusterSize: null }, projected);
+      },
+      pass: (r) => {
+        if (r?.isError) return false;
+        let out;
+        try {
+          out = JSON.parse(r?.content?.[0]?.text);
+        } catch {
+          return false;
+        }
+        // minClusterSize coerced to default 3, NOT NaN → the 3-task
+        // cluster is detected.
+        return out.minClusterSize === 3 && out.gapCount === 1;
+      },
+    },
     {
       // suggest_theme_for is the theme-level mirror — same shape,
       // returns ranked matches against an arbitrary description.
@@ -4158,6 +5672,155 @@ async function runSelftest() {
         );
       },
     },
+    {
+      // Seed-workspace guard: no arg + no snapshot + env default ==
+      // seed workspace "default" → refuse the mutator. Env is set/
+      // restored around the call; snapshot forced absent.
+      name: "seed-workspace write refused when resolved from env default",
+      fn: async () => {
+        const prevR = process.env.ROADMAPPER_WORKSPACE_ID;
+        const prevS = process.env.SUPABASE_WORKSPACE_ID;
+        try {
+          resetSession();
+          session.rubricFetchedAt = Date.now();
+          __setSnapshotWorkspaceForTest(null);
+          process.env.ROADMAPPER_WORKSPACE_ID = "default";
+          delete process.env.SUPABASE_WORKSPACE_ID;
+          return await handle({
+            id: 38,
+            method: "tools/call",
+            params: {
+              name: "propose_task",
+              arguments: { capabilityId: "CAP-X", title: "x", effort: "M" },
+            },
+          });
+        } finally {
+          __setSnapshotWorkspaceForTest(undefined);
+          if (prevR === undefined) delete process.env.ROADMAPPER_WORKSPACE_ID;
+          else process.env.ROADMAPPER_WORKSPACE_ID = prevR;
+          if (prevS !== undefined) process.env.SUPABASE_WORKSPACE_ID = prevS;
+        }
+      },
+      pass: (r) => {
+        if (!r?.result?.isError) return false;
+        const txt = r.result.content?.[0]?.text ?? "";
+        return txt.includes("seed/demo workspace");
+      },
+    },
+    {
+      // Explicit workspaceId="default" makes the source "arg", a
+      // deliberate choice — the seed guard must NOT fire. The call
+      // then fails downstream (no write auth), proving the guard let
+      // it through.
+      name: "explicit workspaceId arg bypasses the seed-workspace guard",
+      fn: async () => {
+        const prevR = process.env.ROADMAPPER_WORKSPACE_ID;
+        try {
+          resetSession();
+          session.rubricFetchedAt = Date.now();
+          __setSnapshotWorkspaceForTest(null);
+          process.env.ROADMAPPER_WORKSPACE_ID = "default";
+          return await handle({
+            id: 39,
+            method: "tools/call",
+            params: {
+              name: "propose_task",
+              arguments: {
+                capabilityId: "CAP-X",
+                title: "x",
+                effort: "M",
+                workspaceId: "default",
+              },
+            },
+          });
+        } finally {
+          __setSnapshotWorkspaceForTest(undefined);
+          if (prevR === undefined) delete process.env.ROADMAPPER_WORKSPACE_ID;
+          else process.env.ROADMAPPER_WORKSPACE_ID = prevR;
+        }
+      },
+      pass: (r) => {
+        const txt = r?.result?.content?.[0]?.text ?? "";
+        return !txt.includes("seed/demo workspace");
+      },
+    },
+    {
+      // ROADMAPPER_ALLOW_SEED_WORKSPACE=1 opts out of the seed guard
+      // (parity with the cross-workspace override). Guard must NOT fire
+      // even when resolved from the env default.
+      name: "ROADMAPPER_ALLOW_SEED_WORKSPACE=1 disables the seed-workspace guard",
+      fn: async () => {
+        const prevR = process.env.ROADMAPPER_WORKSPACE_ID;
+        const prevS = process.env.SUPABASE_WORKSPACE_ID;
+        const prevAllow = process.env.ROADMAPPER_ALLOW_SEED_WORKSPACE;
+        try {
+          resetSession();
+          session.rubricFetchedAt = Date.now();
+          __setSnapshotWorkspaceForTest(null);
+          process.env.ROADMAPPER_WORKSPACE_ID = "default";
+          delete process.env.SUPABASE_WORKSPACE_ID;
+          process.env.ROADMAPPER_ALLOW_SEED_WORKSPACE = "1";
+          return await handle({
+            id: 138,
+            method: "tools/call",
+            params: {
+              name: "propose_task",
+              arguments: { capabilityId: "CAP-X", title: "x", effort: "M" },
+            },
+          });
+        } finally {
+          __setSnapshotWorkspaceForTest(undefined);
+          if (prevR === undefined) delete process.env.ROADMAPPER_WORKSPACE_ID;
+          else process.env.ROADMAPPER_WORKSPACE_ID = prevR;
+          if (prevS !== undefined) process.env.SUPABASE_WORKSPACE_ID = prevS;
+          if (prevAllow === undefined)
+            delete process.env.ROADMAPPER_ALLOW_SEED_WORKSPACE;
+          else process.env.ROADMAPPER_ALLOW_SEED_WORKSPACE = prevAllow;
+        }
+      },
+      pass: (r) => {
+        const txt = r?.result?.content?.[0]?.text ?? "";
+        return !txt.includes("seed/demo workspace");
+      },
+    },
+    {
+      // dryRun is non-destructive validation — it must pass BOTH guards
+      // even when resolved from the seed env default.
+      name: "dryRun bypasses the seed-workspace guard",
+      fn: async () => {
+        const prevR = process.env.ROADMAPPER_WORKSPACE_ID;
+        const prevS = process.env.SUPABASE_WORKSPACE_ID;
+        try {
+          resetSession();
+          session.rubricFetchedAt = Date.now();
+          __setSnapshotWorkspaceForTest(null);
+          process.env.ROADMAPPER_WORKSPACE_ID = "default";
+          delete process.env.SUPABASE_WORKSPACE_ID;
+          return await handle({
+            id: 139,
+            method: "tools/call",
+            params: {
+              name: "propose_task",
+              arguments: {
+                capabilityId: "CAP-X",
+                title: "x",
+                effort: "M",
+                dryRun: true,
+              },
+            },
+          });
+        } finally {
+          __setSnapshotWorkspaceForTest(undefined);
+          if (prevR === undefined) delete process.env.ROADMAPPER_WORKSPACE_ID;
+          else process.env.ROADMAPPER_WORKSPACE_ID = prevR;
+          if (prevS !== undefined) process.env.SUPABASE_WORKSPACE_ID = prevS;
+        }
+      },
+      pass: (r) => {
+        const txt = r?.result?.content?.[0]?.text ?? "";
+        return !txt.includes("seed/demo workspace");
+      },
+    },
     {
       // record_outcome_reading rejects missing value.
       name: "record_outcome_reading (missing value returns error result)",
@@ -4242,6 +5905,59 @@ async function runSelftest() {
         return !txt.includes("Refusing cross-workspace");
       },
     },
+    {
+      // Root-derived workspace (repo→repo_workspace_map) beats the cwd
+      // snapshot AND the env default. This is the multi-repo fix: the
+      // repo the agent is actually in wins.
+      name: "root workspace (repo map) beats snapshot in resolution order",
+      fn: () => {
+        try {
+          __setRootWorkspaceForTest("ws-from-repo", "owner/repo");
+          __setSnapshotWorkspaceForTest("ws-from-snapshot");
+          const { id, source } = resolveWorkspaceWithSource();
+          return { result: { id, source } };
+        } finally {
+          __setRootWorkspaceForTest(undefined);
+          __setSnapshotWorkspaceForTest(undefined);
+        }
+      },
+      pass: (r) =>
+        r?.result?.id === "ws-from-repo" && r?.result?.source === "repo",
+    },
+    {
+      // With no root mapping, resolution falls back to the snapshot —
+      // the existing offline path must still work.
+      name: "resolution falls back to snapshot when no root mapping",
+      fn: () => {
+        try {
+          __setRootWorkspaceForTest(null);
+          __setSnapshotWorkspaceForTest("ws-from-snapshot");
+          const { id, source } = resolveWorkspaceWithSource();
+          return { result: { id, source } };
+        } finally {
+          __setRootWorkspaceForTest(undefined);
+          __setSnapshotWorkspaceForTest(undefined);
+        }
+      },
+      pass: (r) =>
+        r?.result?.id === "ws-from-snapshot" && r?.result?.source === "snapshot",
+    },
+    {
+      // setClientRoots parses both file:// URIs and bare paths and
+      // invalidates the cached resolution.
+      name: "setClientRoots parses file:// URIs and bare paths",
+      fn: () => {
+        __setRootWorkspaceForTest("stale"); // should be invalidated
+        setClientRoots([
+          { uri: "file:///Users/x/proj-a" },
+          { uri: "/Users/x/proj-b" },
+        ]);
+        return { result: { cleared: rootWorkspaceId() } };
+      },
+      // After setClientRoots, the cache is reset to undefined → rootWorkspaceId()
+      // returns null until resolveRootWorkspace() runs. So "cleared" must be null.
+      pass: (r) => r?.result?.cleared === null,
+    },
   ];
 
   let passed = 0;
@@ -4290,8 +6006,19 @@ if (process.argv.includes("--selftest")) {
         log("bad json", line.slice(0, 200));
         continue;
       }
+      // A message with no `method` but a result/error is a RESPONSE to a
+      // request WE sent (e.g. our roots/list). Route it, don't dispatch.
+      if (msg.method === undefined && (msg.result !== undefined || msg.error !== undefined)) {
+        await handleClientResponse(msg);
+        continue;
+      }
       const response = await handle(msg);
       if (response) send(response);
+      // After answering initialize, ask the client for its roots so we
+      // can resolve the per-repo workspace. Done here (not inside the
+      // handler) because the client only starts listening for our
+      // requests once it has our initialize result in hand.
+      if (msg.method === "initialize") requestClientRoots();
     }
   });
 
@@ -4327,4 +6054,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();
 }