@adrata/adrata-mcp 1.0.1 → 1.0.2

package/README.md

@@ -10,7 +10,7 @@ This package is also published as **[`@adrata/starfield-mcp`](https://www.npmjs.
 (binary `starfield-mcp`), for people wiring a coding agent to their Starfield
 board rather than to the CRM. It is not a fork and not a subset: it depends on
 this package, defaults `ADRATA_MCP_SERVER_NAME` to `Starfield` so the client's
-server list says Starfield, and imports the same `server.js`. Same 233 tools,
+server list says Starfield, and imports the same `server.js`. Same governed tool surface,
 same tiers, same governed-write contract, and nothing to keep in sync.
 
 Install whichever name matches what you are doing. If you already have one, you

package/access/auth.js

@@ -16,10 +16,27 @@
  */
 
 import { TIERS, getToolTier, tierSatisfies } from './tiers.js';
-import { loadTokens, getValidToken, OAUTH_SCOPE, describeOAuthScopeCapabilities } from './oauth.js';
-import { existsSync, readFileSync } from 'node:fs';
+import {
+  loadTokens,
+  getValidToken,
+  OAUTH_SCOPE,
+  describeOAuthScopeCapabilities,
+  ReconnectRequiredError,
+  TransientRefreshError,
+} from './oauth.js';
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute, resolve, join } from 'node:path';
+import { dirname, isAbsolute, resolve, join } from 'node:path';
 
 const DEFAULT_CLI_CONFIG_PATH = join(homedir(), '.config', 'adrata', 'cli.json');
 const DEFAULT_AGENT_CONFIG_PATH = join(homedir(), '.config', 'adrata', 'agent.json');
@@ -53,7 +70,7 @@ export function loadCliConfig() {
 
 /**
  * Read the shared agent session (device-flow OAuth, written by `adrata login`).
- * Returns { accessToken, apiBase, workspaceId } or null when absent/unusable.
+ * Returns the full refreshable session or null when absent/unusable.
  */
 export function loadAgentSession() {
   try {
@@ -66,8 +83,14 @@ export function loadAgentSession() {
     if (!accessToken) return null;
     return {
       accessToken,
+      refreshToken: str('refreshToken'),
+      accessExpiresAt:
+        typeof parsed.accessExpiresAt === 'number' && Number.isFinite(parsed.accessExpiresAt)
+          ? parsed.accessExpiresAt
+          : null,
       apiBase: str('apiBase')?.replace(/\/+$/, '') ?? null,
       workspaceId: str('workspaceId'),
+      user: parsed.user && typeof parsed.user === 'object' ? parsed.user : null,
     };
   } catch {
     return null;
@@ -119,6 +142,7 @@ export function authenticate() {
       authenticated: true,
       source: 'agent_config',
       issuerApiBase: agentSession.apiBase || null,
+      _agentSession: agentSession,
     };
   }
 
@@ -173,6 +197,171 @@ export function reauthenticate() {
   return authenticate();
 }
 
+const AGENT_REFRESH_BUFFER_MS = 5 * 60 * 1000;
+const AGENT_REFRESH_LOCK_STALE_MS = 30_000;
+const AGENT_REFRESH_LOCK_WAIT_MS = 10_000;
+const AGENT_REFRESH_MAX_ATTEMPTS = 3;
+const AGENT_REFRESH_BASE_DELAY_MS = 250;
+const _agentRefreshInflight = new Map();
+
+function agentSessionFresh(session) {
+  return (
+    typeof session?.accessExpiresAt === 'number' &&
+    Date.now() < session.accessExpiresAt - AGENT_REFRESH_BUFFER_MS
+  );
+}
+
+function persistAgentSession(path, session) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(session, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+function agentRefreshBackoffDelay(attempt) {
+  const base = AGENT_REFRESH_BASE_DELAY_MS * 2 ** (attempt - 1);
+  return base + Math.floor(Math.random() * AGENT_REFRESH_BASE_DELAY_MS);
+}
+
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function acquireAgentRefreshLock(path) {
+  const lockPath = `${path}.refresh.lock`;
+  const deadline = Date.now() + AGENT_REFRESH_LOCK_WAIT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const fd = openSync(lockPath, 'wx', 0o600);
+      closeSync(fd);
+      return () => {
+        try {
+          unlinkSync(lockPath);
+        } catch {
+          // Another process may have cleaned a stale lock after this process was interrupted.
+        }
+      };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        if (Date.now() - statSync(lockPath).mtimeMs > AGENT_REFRESH_LOCK_STALE_MS) {
+          unlinkSync(lockPath);
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  }
+  throw new TransientRefreshError('Timed out waiting for another MCP client to refresh the shared session.');
+}
+
+/**
+ * Return a valid token from the shared `adrata login` session.
+ *
+ * Refresh tokens rotate, while several MCP hosts may read the same agent.json. The in-process
+ * single-flight prevents duplicate refreshes inside one server and the adjacent lock file extends
+ * that guarantee across Codex/Claude/Cursor processes. The winner atomically replaces agent.json;
+ * waiters re-read it and reuse the rotated token instead of presenting the now-revoked old one.
+ */
+export async function getValidAgentToken(
+  apiBase,
+  { fetchImpl = fetch, forceRefresh = false, rejectedToken = null } = {},
+) {
+  const path = getAgentConfigPath();
+  const quick = loadAgentSession();
+  if (!quick) return null;
+  if (!forceRefresh && agentSessionFresh(quick)) return quick.accessToken;
+
+  const key = `${path}|${new URL(apiBase).origin}`;
+  const existing = _agentRefreshInflight.get(key);
+  if (existing) return existing;
+
+  const inflight = (async () => {
+    const release = await acquireAgentRefreshLock(path);
+    try {
+      const current = loadAgentSession();
+      if (!current) return null;
+      if (current.apiBase && new URL(current.apiBase).origin !== new URL(apiBase).origin) {
+        throw new ReconnectRequiredError(
+          'Shared agent session/API mismatch. Run adrata login against the target environment.',
+        );
+      }
+      if (rejectedToken && current.accessToken !== rejectedToken) return current.accessToken;
+      if (!forceRefresh && agentSessionFresh(current)) return current.accessToken;
+      if (!current.refreshToken) {
+        throw new ReconnectRequiredError(
+          'The shared adrata login session has no refresh token. Run adrata login once to reconnect.',
+        );
+      }
+
+      let data;
+      let lastTransientError;
+      for (let attempt = 1; attempt <= AGENT_REFRESH_MAX_ATTEMPTS; attempt += 1) {
+        let response;
+        try {
+          response = await fetchImpl(`${apiBase.replace(/\/+$/, '')}/api/auth/refresh-token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ refreshToken: current.refreshToken }),
+          });
+        } catch (error) {
+          lastTransientError = new TransientRefreshError(
+            `Shared session refresh network error: ${error.message}`,
+            { cause: error },
+          );
+          if (attempt < AGENT_REFRESH_MAX_ATTEMPTS) {
+            await wait(agentRefreshBackoffDelay(attempt));
+            continue;
+          }
+          throw lastTransientError;
+        }
+
+        data = await response.json().catch(() => ({}));
+        if (response.ok) break;
+        if (response.status === 429 || response.status >= 500) {
+          lastTransientError = new TransientRefreshError(
+            `Shared session refresh failed (${response.status}).`,
+          );
+          if (attempt < AGENT_REFRESH_MAX_ATTEMPTS) {
+            await wait(agentRefreshBackoffDelay(attempt));
+            continue;
+          }
+          throw lastTransientError;
+        }
+        throw new ReconnectRequiredError(
+          `Shared adrata login refresh was rejected (${response.status}). Run adrata login once to reconnect.`,
+        );
+      }
+
+      if (!data?.accessToken || !data?.refreshToken || !Number.isFinite(data?.expires)) {
+        throw new TransientRefreshError('Shared session refresh returned an incomplete token response.');
+      }
+
+      const workspaceId =
+        data.user?.activeWorkspaceId ?? data.user?.workspaces?.[0]?.id ?? current.workspaceId;
+      const updated = {
+        ...current,
+        apiBase: apiBase.replace(/\/+$/, ''),
+        accessToken: data.accessToken,
+        refreshToken: data.refreshToken,
+        accessExpiresAt: data.expires * 1000,
+        workspaceId,
+        user: data.user ?? current.user,
+        updatedAt: new Date().toISOString(),
+      };
+      persistAgentSession(path, updated);
+      return updated.accessToken;
+    } finally {
+      release();
+    }
+  })().finally(() => _agentRefreshInflight.delete(key));
+
+  _agentRefreshInflight.set(key, inflight);
+  return inflight;
+}
+
 export function assertOAuthIssuerMatchesTarget(authContext, apiBase) {
   const issuerBound = authContext.source === 'stored' || authContext.source === 'agent_config';
   if (!issuerBound || !authContext.issuerApiBase) return;

package/access/oauth.js

@@ -51,6 +51,18 @@ export const OAUTH_CALLBACK_ENDPOINTS = Object.freeze([
   { host: '::1', url: `http://[::1]:${CALLBACK_PORT}${CALLBACK_PATH}` },
 ]);
 const OAUTH_BASE_PATH = '/api/v1/enterprise/oauth';
+export const SEEDED_PUBLIC_CLIENT_ID = 'adrata-mcp-client';
+// The static production client's registered read ceiling. Newer optional read
+// families are available through DCR, but asking the seeded client for them
+// makes `/authorize` reject the WHOLE request before it can present consent.
+// Write scopes are intentionally not listed: current APIs may elevate those
+// only after a signed-in workspace member approves them.
+export const SEEDED_PUBLIC_READ_SCOPE = [
+  'read:companies', 'read:people', 'read:opportunities', 'read:actions',
+  'read:pipeline', 'read:speedrun', 'read:signals', 'read:search',
+  'read:analytics', 'read:buyer-groups', 'read:tasks', 'read:integrations',
+  'ai:base',
+].join(' ');
 // Read-only surface + the AI dispatcher. `ai:base` is required for anything
 // routing through POST /api/v1/ai-crm-tools/execute. The additional read:*
 // scopes unblock ~30 tools that scope_guard gates behind their own families
@@ -288,7 +300,12 @@ export async function registerNativeClient(
   });
   const data = await res.json().catch(() => ({}));
   if (!res.ok) {
-    throw new Error(`OAuth client registration failed: ${res.status} ${JSON.stringify(data).slice(0, 200)}`);
+    const error = new Error(
+      `OAuth client registration failed: ${res.status} ${JSON.stringify(data).slice(0, 200)}`
+    );
+    error.status = res.status;
+    error.oauthCode = data?.error;
+    throw error;
   }
   if (typeof data.client_id !== 'string' || !data.client_id) {
     throw new Error('OAuth client registration returned no client_id.');
@@ -303,6 +320,61 @@ export async function registerNativeClient(
   };
 }
 
+/**
+ * Choose the public client for one connection attempt.
+ *
+ * Dynamic registration is preferred because it narrows each installation to
+ * its exact loopback redirect. Production also carries a seeded public PKCE
+ * client for continuity during a rollout, behind a proxy that blocks DCR, or
+ * after the per-IP DCR ceiling is reached. A public client id is not a secret;
+ * the authorization code remains bound to the exact redirect and PKCE
+ * verifier, and write scopes still require the signed-in human consent step.
+ */
+export async function registrationForConnection({
+  apiBase,
+  redirectUris,
+  requestedScope,
+  fetchImpl = fetch,
+  configuredClientId = process.env.ADRATA_MCP_CLIENT_ID?.trim(),
+} = {}) {
+  if (configuredClientId) {
+    return {
+      clientId: configuredClientId,
+      tokenEndpointAuthMethod: 'none',
+      clientRegistration: 'configured',
+    };
+  }
+
+  try {
+    return {
+      ...(await registerNativeClient(apiBase, fetchImpl, redirectUris, requestedScope)),
+      clientRegistration: 'dynamic',
+    };
+  } catch (error) {
+    // These responses mean registration is unavailable, not that the
+    // authorization itself was refused. Do not mask a malformed request (400)
+    // or an API failure (5xx): both need fixing rather than a second path.
+    if (![403, 404, 429].includes(error?.status)) throw error;
+    return {
+      clientId: SEEDED_PUBLIC_CLIENT_ID,
+      tokenEndpointAuthMethod: 'none',
+      clientRegistration: 'seeded_fallback',
+      // Keep requested write scopes: they are not self-granted here. The
+      // authorize endpoint intersects them with the authenticated approver's
+      // role and requires explicit consent. Only the extra READ families need
+      // narrowing to the seeded client's registered ceiling.
+      scope: [
+        ...SEEDED_PUBLIC_READ_SCOPE.split(' ').filter((scope) =>
+          String(requestedScope ?? '').split(/\s+/).includes(scope)
+        ),
+        ...String(requestedScope ?? '')
+          .split(/\s+/)
+          .filter((scope) => scope.startsWith('write:')),
+      ].join(' '),
+    };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Encryption helpers
 // ---------------------------------------------------------------------------
@@ -901,24 +973,26 @@ export async function connectWorkspace(apiBase, { writeAccess = false } = {}) {
   // Prefer an explicitly provisioned client when an operator supplies one.
   // Otherwise use RFC 7591 DCR so every installation gets a real public client
   // instead of relying on a database seed or a secret embedded in npm.
-  const configuredClientId = process.env.ADRATA_MCP_CLIENT_ID?.trim();
   let registration;
   try {
-    registration = configuredClientId
-      ? { clientId: configuredClientId, tokenEndpointAuthMethod: 'none' }
-      : await registerNativeClient(apiBase, fetch, [callbackServer.redirectUri], requestedScope);
+    registration = await registrationForConnection({
+      apiBase,
+      redirectUris: [callbackServer.redirectUri],
+      requestedScope,
+    });
   } catch (error) {
     callbackServer.close();
     throw error;
   }
   const clientId = registration.clientId;
+  const authorizationScope = registration.scope || requestedScope;
   const authUrl = buildAuthUrl(
     apiBase,
     clientId,
     callbackServer.redirectUri,
     state,
     pkce,
-    requestedScope,
+    authorizationScope,
   ).url;
 
   if (process.env.ADRATA_MCP_PRINT_AUTH_URL === '1') {
@@ -948,9 +1022,9 @@ export async function connectWorkspace(apiBase, { writeAccess = false } = {}) {
     // The SERVER's granted scope wins. If the authorization server narrows the
     // grant (unregistered client scope, consent declined), the stored scope
     // must reflect what was actually granted -- never what we asked for.
-    scope: tokenResult.scope || requestedScope,
+    scope: tokenResult.scope || authorizationScope,
     clientId,
-    clientRegistration: configuredClientId ? 'configured' : 'dynamic',
+    clientRegistration: registration.clientRegistration,
     tokenEndpointAuthMethod: registration.tokenEndpointAuthMethod,
     resource: canonicalResource(),
     apiBase,

package/access/tiers.js

@@ -100,6 +100,26 @@ export const TOOL_TIERS = {
   list_overdue_actions: TIERS.PRO,
   list_today_actions: TIERS.PRO,
   list_notes: TIERS.PRO,
+
+  // --- The nine spaces, as read surfaces ---
+  //
+  // Every one of these is a READ over data a seller can already see in the app, so they sit at
+  // PRO alongside the record reads they summarise. None mutates anything; the writes behind these
+  // surfaces (a stage move, an edit) go through the existing governed tools rather than getting a
+  // second, laxer door here.
+  //
+  // list_spaces is the map of what a workspace can actually open, so it answers the same question
+  // the chooser does and is deliberately the cheapest call in the set.
+  list_spaces: TIERS.PRO,
+  get_pipeline_board: TIERS.PRO,
+  get_calendar_agenda: TIERS.PRO,
+  get_customer_health: TIERS.PRO,
+  get_market_overview: TIERS.PRO,
+  list_content_files: TIERS.PRO,
+  // Finance and the connector estate describe the WORKSPACE rather than a seller's book, so they
+  // sit with the other administrative reads: an operator question, not a selling one.
+  get_finance_overview: TIERS.ENTERPRISE,
+  list_workspace_connectors: TIERS.ENTERPRISE,
   log_interaction: TIERS.PRO,
 
   // --- ENTERPRISE tier: CRM CRUD, sequences, campaigns, admin, bulk ---
@@ -166,6 +186,9 @@ export const TOOL_TIERS = {
   adrata_api_request: TIERS.ENTERPRISE,
   adrata_ai_tool_catalog: TIERS.ENTERPRISE,
   adrata_ai_tool_execute: TIERS.ENTERPRISE,
+  search_capabilities: TIERS.ENTERPRISE,
+  describe_capability: TIERS.ENTERPRISE,
+  run_capability: TIERS.ENTERPRISE,
   // Sloan (AI executive assistant) — same governed dispatcher path as
   // adrata_ai_tool_execute, so same tier.
   sloan_status: TIERS.ENTERPRISE,
@@ -195,18 +218,28 @@ export const TOOL_TIERS = {
   // the tool — only exists on an OAuth token.
   list_my_work_items: TIERS.ENTERPRISE,
   list_work_boards: TIERS.ENTERPRISE,
+  get_work_item_delivery_evidence: TIERS.ENTERPRISE,
+  audit_work_hub: TIERS.ENTERPRISE,
+  list_work_item_acceptance_criteria: TIERS.ENTERPRISE,
   get_work_board: TIERS.ENTERPRISE,
   get_work_item: TIERS.ENTERPRISE,
   get_work_item_history: TIERS.ENTERPRISE,
   get_work_item_comments: TIERS.ENTERPRISE,
   get_work_board_rollup: TIERS.ENTERPRISE,
   list_work_board_rollups: TIERS.ENTERPRISE,
+  set_work_board_archived: TIERS.ENTERPRISE,
+  set_work_board_column_wip_limit: TIERS.ENTERPRISE,
   move_work_item: TIERS.ENTERPRISE,
   set_work_item_tag: TIERS.ENTERPRISE,
   set_work_item_kind: TIERS.ENTERPRISE,
   create_work_item: TIERS.ENTERPRISE,
+  add_work_item_acceptance_criterion: TIERS.ENTERPRISE,
   comment_on_work_item: TIERS.ENTERPRISE,
   flag_work_item: TIERS.ENTERPRISE,
+  // The containers above the cards, and the "add this to the roadmap" verb.
+  // Same reasoning as every board tool: scopes are real workspace records.
+  list_work_scopes: TIERS.ENTERPRISE,
+  add_to_roadmap: TIERS.ENTERPRISE,
 
   // --- ENTERPRISE tier: Paper desktop app surfaces ---
   paper_list_documents: TIERS.ENTERPRISE,

package/api-bridge.js

@@ -91,11 +91,19 @@ const ALLOWED_PREFIXES = [
   '/api/v1/email',
   '/api/v1/email-analytics',
   '/api/v1/email-deliverability',
+  // `matchesPathPrefix` is segment-boundary matched, so `/api/v1/email` does
+  // NOT annex `/api/v1/email-drafts` — the draft surface the Email app reads
+  // and writes on every compose was outside the allowlist entirely.
+  '/api/v1/email-drafts',
   '/api/v1/email-intelligence',
   '/api/v1/email-provisioning',
   '/api/v1/emails',
   '/api/v1/engagement',
-  '/api/v1/entities',
+  // What the workspace is entitled to. The nine-space chooser at /spaces reads
+  // exactly this and nothing else, so without it an agent cannot answer "which
+  // spaces does this workspace even have" — the first question about the app's
+  // new top-level shape.
+  '/api/v1/entitlements',
   '/api/v1/env-audit',
   '/api/v1/events',
   '/api/v1/evidence',
@@ -121,8 +129,13 @@ const ALLOWED_PREFIXES = [
   '/api/v1/jobs',
   '/api/v1/knowledge',
   '/api/v1/lead-lifecycle',
+  // Same segment-boundary point as email-drafts: `/api/v1/leads` does not
+  // annex `/api/v1/lead-lists`. The Deals list joins lead lists and their
+  // members, so the list surface was half-reachable without this.
+  '/api/v1/lead-lists',
   '/api/v1/lead-routing',
   '/api/v1/leads',
+  '/api/v1/lists',
   '/api/v1/leaderboard',
   '/api/v1/linkedin',
   '/api/v1/media',
@@ -158,8 +171,6 @@ const ALLOWED_PREFIXES = [
   '/api/v1/retention',
   '/api/v1/revenue',
   '/api/v1/revenue-cloud',
-  '/api/v1/sales',
-  '/api/v1/scim',
   '/api/v1/scoring',
   '/api/v1/security',
   '/api/v1/self-service',
@@ -169,7 +180,6 @@ const ALLOWED_PREFIXES = [
   '/api/v1/signal-triggers',
   '/api/v1/simple-features',
   '/api/v1/sms',
-  '/api/v1/sso',
   '/api/v1/speedrun',
   '/api/v1/supersets',
   '/api/v1/survival',
@@ -179,6 +189,7 @@ const ALLOWED_PREFIXES = [
   '/api/v1/targets',
   '/api/v1/team',
   '/api/v1/trash',
+  '/api/v1/triggers',
   '/api/v1/usage',
   '/api/v1/user-voice-profile',
   '/api/v1/users',
@@ -192,12 +203,36 @@ const ALLOWED_PREFIXES = [
   '/api/v1/work-board-rollups',
   '/api/v1/work-boards',
   '/api/v1/work-items',
+  // The containers above the cards (initiative / epic / feature) and the
+  // "add this to the roadmap" verb. Creating an epic proposal is a governed
+  // write like any other; the strategic commitment itself still moves through
+  // spoq/ PRs (company/decisions/2026-08-06-spoq-roadmap-sync.md).
+  '/api/v1/work-scopes',
   '/api/v1/workflow-runtime',
   '/api/v1/workflows',
   '/api/v1/workspace',
   '/api/v1/workspace-features',
   '/api/v1/workspace-settings',
   '/api/v1/zoho',
+  // ---------------------------------------------------------------------
+  // /api/v2 — the desktop read models and the aimed send path.
+  //
+  // Until this block existed the bridge allowlisted `/api/v1` exclusively, so
+  // EVERY v2 path failed `path is outside the agent bridge allowlist`. That
+  // was not a niche gap: the app's Email and Calendar surfaces read from v2,
+  // not v1. `GET /api/v2/emails/threads` backs the inbox list,
+  // `GET /api/v2/emails/counts` backs the folder badges, and
+  // `GET /api/v2/events/calendar` backs the entire agenda. A person could open
+  // their inbox and their calendar; an agent could reach neither, while the
+  // v1 write paths for the same records (PUT /api/v1/events/{id}, the draft
+  // routes) were allowlisted the whole time. The bridge could modify a
+  // calendar it could not read.
+  //
+  // The v2 namespace is deliberately small — `code/api/src/routes/v2/mod.rs`
+  // nests exactly `/emails` and `/events` — so these two prefixes are the
+  // whole surface, not a wildcard.
+  '/api/v2/emails',
+  '/api/v2/events',
 ];
 
 function matchesPathPrefix(path, prefix) {
@@ -232,10 +267,38 @@ const PATH_WRITE_SCOPES = [
   ['/api/v1/agent-tasks', 'write:tasks'],
   ['/api/v1/tasks', 'write:tasks'],
   ['/api/v1/actions', 'write:actions'],
+  // Starfield boards. A card IS a task, so the API's scope_guard maps all three
+  // board families onto the SAME read:tasks/write:tasks pair rather than a new
+  // scope family — see `required_scopes_for` in
+  // code/api/crates/middleware/src/scope_guard/mod.rs and the test
+  // `work_board_routes_are_reachable_by_the_credential_the_mcp_actually_issues`.
+  // Without these three rows a board write previewed as
+  // `requiredScope: "unknown (no mapping for this path)"` with `wouldSend: true`,
+  // so the preview could not warn that the connection lacked write:tasks — the
+  // exact "safe preview that predicts nothing" this map exists to prevent.
+  // All three are listed separately because `matchesPathPrefix` is
+  // segment-boundary matched: `/work-boards` does not annex
+  // `/work-board-rollups`.
+  ['/api/v1/work-boards', 'write:tasks'],
+  ['/api/v1/work-items', 'write:tasks'],
+  ['/api/v1/work-board-rollups', 'write:tasks'],
 ];
 
+/**
+ * The API classifies a path AFTER stripping its version prefix, so
+ * `/api/v2/emails/direct` is scoped by exactly the same rules as
+ * `/api/v1/emails/direct` (`VERSIONED_API_PREFIXES` in
+ * code/api/crates/middleware/src/scope_guard/mod.rs). Mirror that here instead
+ * of duplicating every row under a second version — a duplicated map is a map
+ * that drifts, and a v2 path silently falling through to "no mapping" is the
+ * "preview that predicts nothing" failure this module exists to prevent.
+ */
+function toScopeClassificationPath(path) {
+  return path.startsWith('/api/v2/') ? `/api/v1/${path.slice('/api/v2/'.length)}` : path;
+}
+
 export function requiredWriteScopeForPath(path) {
-  const normalized = normalizeApiPath(path);
+  const normalized = toScopeClassificationPath(normalizeApiPath(path));
   let best = null;
   for (const [prefix, scope] of PATH_WRITE_SCOPES) {
     if (matchesPathPrefix(normalized, prefix)) {