@adrata/adrata-mcp 1.0.7 → 1.0.8

package/README.md

@@ -418,12 +418,58 @@ Actions support `metadata` -- a JSONB object for type-specific data. Use it for
 "Log a linkedin_connection_request action for this person with metadata containing the message I sent"
 ```
 
+### Running several MCP processes under separate identities
+
+`~/.config/adrata/agent.json` -- the session `adrata login` writes -- is
+machine-wide. Every MCP process on a host where anyone has ever run
+`adrata login` therefore authenticates as that one person, including a process
+that was launched with its own `ADRATA_API_KEY`: the key is still sent as
+`X-API-Key`, but the bearer token is what the API resolves the caller from.
+
+Usually that is exactly right. It is wrong when several processes on one host
+are supposed to act as *different* principals -- a fleet of QA lanes, each
+holding its own key so that its board writes are graded as an independent agent
+rather than as the shared human. The API is not confused in that case: it
+correctly grades a human session's write as human, records it, returns `200`,
+and counts it toward nothing.
+
+Set `ADRATA_MCP_PREFER_API_KEY=1` in that process's env, alongside its
+`ADRATA_API_KEY`, and it acts as its own `api_key:<id>` actor.
+
+```jsonc
+{
+  "mcpServers": {
+    "adrata": {
+      "command": "npx",
+      "args": ["-y", "@adrata/starfield-mcp@latest"],
+      "env": {
+        "ADRATA_API_KEY": "ak_this_lanes_own_key",
+        "ADRATA_MCP_PREFER_API_KEY": "1"
+      }
+    }
+  }
+}
+```
+
+Three things it deliberately does not do:
+
+- **It only reads the environment variable.** A token sitting in
+  `~/.config/adrata/cli.json` is ambient machine state, not a statement of
+  intent by whoever launched this process, and never triggers the preference.
+- **It does not outrank `ADRATA_OAUTH_TOKEN`**, which stays first in the chain.
+- **It does not touch named identity pools** (`ADRATA_MCP_IDENTITY_POOL`), which
+  return before the credential chain is consulted at all.
+
+With the flag unset -- the default, and every ordinary single-user install --
+the credential chain is byte-for-byte what it was.
+
 ## Environment Variables
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `ADRATA_API_KEY` | No | -- | Your API key from Settings > API Keys. Enables pro tier. |
 | `ADRATA_OAUTH_TOKEN` | No | -- | OAuth bearer token. Enables enterprise tier. |
+| `ADRATA_MCP_PREFER_API_KEY` | No | unset (off) | `1`/`true`/`yes`/`on` makes an **env-var** `ADRATA_API_KEY` outrank the shared `adrata login` session and any stored `connect_workspace` session, and grants it enterprise tier. Leave it unset unless this process was deliberately given its own credential -- see below. |
 | `ADRATA_API_URL` | No | `https://api.adrata.com` | API base URL |
 | `ADRATA_MCP_SERVER_NAME` | No | `@adrata/adrata-mcp` | Display name reported in `serverInfo`. `@adrata/starfield-mcp` sets it to `Starfield`. Does not change the tool prefix, which comes from your client's config key. |
 | `ADRATA_MCP_TRANSPORT` | No | `stdio` | Transport: `stdio` or `http` |

package/access/auth.js

@@ -13,6 +13,10 @@
  * terminal agent, and this MCP server all read the same file, so one device-flow
  * sign-in serves all three surfaces. The MCP's own tokens.json (written by
  * connect_workspace) and the legacy cli.json keep working unchanged.
+ *
+ * ONE OPT-IN REORDERS THAT LIST: ADRATA_MCP_PREFER_API_KEY. See
+ * `preferExplicitApiKey` below for why it exists and what it deliberately does
+ * not do.
  */
 
 import { TIERS, getToolTier, tierSatisfies } from './tiers.js';
@@ -98,11 +102,57 @@ export function loadAgentSession() {
   }
 }
 
+/**
+ * Env-var API key ONLY - never the ambient legacy cli.json token.
+ *
+ * The distinction is the whole safety of the opt-in below. An env var is set by
+ * whoever launched this process, for this process; cli.json is machine state a
+ * user may have had for months without knowing. Letting the ambient one reorder
+ * the chain would silently change which identity an ordinary user writes as.
+ */
+export function explicitEnvApiKey(env = process.env) {
+  const key = env.ADRATA_API_KEY?.trim() || env.ADRATA_API_TOKEN?.trim() || '';
+  return key || null;
+}
+
+/**
+ * Should an explicitly-supplied ADRATA_API_KEY outrank the shared on-disk
+ * session? Off unless asked for.
+ *
+ * The problem it solves: the shared `adrata login` session at step 2 is a
+ * MACHINE-WIDE file, so on a host where anyone has ever run `adrata login`,
+ * every MCP process on that host authenticates as that one human - including
+ * processes that were deliberately handed their own distinct API key. The key
+ * is still sent (server.js attaches X-API-Key alongside the bearer), but the
+ * API resolves the bearer, so the caller's identity is the shared human's.
+ *
+ * For a fleet of QA lanes that is not a tier problem, it is an IDENTITY
+ * problem: the API grades a human-token write as Verifier::Human, which counts
+ * zero toward the agent gate, so a lane's verification lands, stores, reads
+ * back fine - and moves nothing. Independence that is declared and not real is
+ * the exact failure the two-gate design exists to prevent.
+ *
+ * Why an opt-in flag rather than flipping precedence outright: precedence here
+ * is machine-wide too. A single-user laptop that has both `adrata login` and an
+ * ADRATA_API_KEY in a shell profile would silently drop from the OAuth session
+ * to an API key, changing the acting identity and the audit trail of every
+ * subsequent write, to fix a problem that user does not have. The flag makes
+ * the caller say "this process was given its own credential on purpose".
+ *
+ * Accepts 1/true/yes/on, case-insensitive; anything else (including unset) is off.
+ */
+export function preferExplicitApiKey(env = process.env) {
+  const raw = env.ADRATA_MCP_PREFER_API_KEY?.trim().toLowerCase();
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
+
 /**
  * Determine the user's tier from environment / stored tokens / API key.
  *
  * Checks (in priority order):
  *   1. ADRATA_OAUTH_TOKEN env var (enterprise)
+ *   1b. ADRATA_API_KEY env var, ONLY when ADRATA_MCP_PREFER_API_KEY is set
+ *       (enterprise — see preferExplicitApiKey)
  *   2. Shared agent session — agent.json from `adrata login` (enterprise)
  *   3. Stored OAuth tokens from connect_workspace flow (enterprise)
  *   4. ADRATA_API_KEY env var / legacy cli.json token (pro)
@@ -170,6 +220,34 @@ export function authenticate() {
     };
   }
 
+  // Opt-in: an explicitly supplied env API key outranks every on-disk store.
+  //
+  // Tier is ENTERPRISE, not PRO, and that is load-bearing rather than
+  // generous. An Adrata API key is a real workspace credential — the API
+  // resolves it to an `api_key:<id>` actor and authorises the governed board
+  // routes on it. Every Starfield board tool is tagged ENTERPRISE in tiers.js,
+  // so leaving this at PRO would hand the caller its own identity and then have
+  // checkToolAccess refuse `move_work_item` and
+  // `satisfy_work_item_acceptance_criterion` before either left the process:
+  // the fix would resolve the credential correctly and still deliver nothing.
+  // The tier here describes what the credential can reach, and this one reaches
+  // the workspace.
+  const preferredApiKey = preferExplicitApiKey() ? explicitEnvApiKey() : null;
+  if (preferredApiKey) {
+    return {
+      tier: TIERS.ENTERPRISE,
+      // No bearer: server.js sends X-API-Key alone, so the API resolves this
+      // process to its own api_key actor instead of the shared human session.
+      token: null,
+      apiKey: preferredApiKey,
+      apiUrl,
+      workspaceId,
+      authenticated: true,
+      source: 'api_key',
+      preferredApiKey: true,
+    };
+  }
+
   // Shared agent session (device-flow OAuth) — the primary on-disk store,
   // shared with the Adrata CLI and the @adrata terminal agent.
   const agentSession = loadAgentSession();

package/access/tiers.js

@@ -245,9 +245,12 @@ export const TOOL_TIERS = {
   move_work_item: TIERS.ENTERPRISE,
   transfer_work_item_between_boards: TIERS.ENTERPRISE,
   set_work_item_tag: TIERS.ENTERPRISE,
+  block_work_item: TIERS.ENTERPRISE,
+  unblock_work_item: TIERS.ENTERPRISE,
   set_work_item_kind: TIERS.ENTERPRISE,
   create_work_item: TIERS.ENTERPRISE,
   add_work_item_acceptance_criterion: TIERS.ENTERPRISE,
+  classify_work_item_acceptance_criterion: TIERS.ENTERPRISE,
   satisfy_work_item_acceptance_criterion: TIERS.ENTERPRISE,
   record_work_item_criterion_engineering_proof: TIERS.ENTERPRISE,
   unsatisfy_work_item_acceptance_criterion: TIERS.ENTERPRISE,

package/http/rate-limit.js

@@ -0,0 +1,159 @@
+/**
+ * Make a 429 legible, and make a hot retry loop impossible.
+ *
+ * The incident this exists for. Measured on the production ALB, 2026-09-02:
+ * request volume went from ~76,000/day to **7,148,120** in one day, of which
+ * **7,059,080 were 4XX** and only 76,913 were 2XX. Real product traffic never
+ * changed — the 2XX count matches the previous day almost exactly. The whole
+ * increase was one client being refused, over and over, at up to 428 requests
+ * per second for four hours.
+ *
+ * A single five-minute ALB access log from the peak:
+ *
+ *     90,898 x 429      one client IP, user-agent "node"
+ *     27,569 x POST /api/v1/work-items/01M17788.../worker-lease/release
+ *     23,131 x POST /api/v1/work-items/01M172QQ.../worker-lease/release
+ *     21,016 x POST /api/v1/work-items/01M1DGCY.../worker-lease/release
+ *
+ * Five card ids account for essentially all of it, so nothing was being
+ * achieved: the same few lease releases were attempted tens of thousands of
+ * times each.
+ *
+ * The cause was not malice or a runaway `for` loop. It was an ERROR MESSAGE.
+ * `api()` in server.js handled 401 (refresh the token and retry once) and
+ * nothing else, so a 429 fell through to the generic shape:
+ *
+ *     API POST /api/v1/work-items/<id>/worker-lease/release → 429: {...}
+ *
+ * That sentence does not say "rate limit", does not say how long to wait, and
+ * does not say "stop". A caller reading it — an agent, a supervisor loop, a
+ * person — sees a transient-looking failure on an operation that MUST succeed
+ * to release a lease, and tries again immediately. The rate limiter then
+ * refuses the retry, producing an identical message, and the loop closes.
+ *
+ * This matters beyond the bill. A lease that cannot be released is a claim that
+ * never clears, and AGENTS.md already records what that does downstream: the
+ * work queue reported `queue=212 claimed=211 free=1` and told every lane "ALL
+ * QUEUES ARE DRAINED. STOP AND REPORT." while 211 of those claims were held on
+ * cards that had already left the column. The storm and the false all-clear are
+ * the same defect seen from two ends.
+ *
+ * So the fix is two things, and the second is the important one:
+ *
+ *   1. Wait and retry a SMALL, BOUNDED number of times, honouring Retry-After.
+ *   2. When the budget is spent, throw a message that names the rate limit and
+ *      tells the caller in plain words not to retry immediately.
+ *
+ * A retry policy alone would not have prevented this. The client was already
+ * "retrying"; it just had no delay and no ceiling, because nothing told it it
+ * was being throttled.
+ */
+
+/**
+ * How many total attempts a single call may make before giving up.
+ *
+ * Deliberately small. The failure mode being prevented is a large budget, and
+ * `rate-limit.test.js` pins the ceiling so raising it has to be a decision
+ * somebody makes on purpose rather than a number that drifts.
+ */
+export const RATE_LIMIT_MAX_ATTEMPTS = 3;
+
+/**
+ * The longest this client will ever block on one attempt.
+ *
+ * A server may legitimately answer `Retry-After: 86400`. Honouring that
+ * literally would hang an MCP tool call for a day, which reads to the caller as
+ * a hang rather than a limit — and a hang gets killed and retried, which is the
+ * behaviour we are trying to remove.
+ */
+export const RATE_LIMIT_MAX_WAIT_MS = 30_000;
+
+/** Base of the exponential backoff, before any server-supplied floor. */
+const BASE_DELAY_MS = 500;
+
+/**
+ * Turn a `Retry-After` header into milliseconds.
+ *
+ * Accepts both forms RFC 9110 allows — delta-seconds and an HTTP-date — and
+ * returns `null` for anything it cannot read. `null` means "we were told
+ * nothing", which is different from "we were told zero", and the caller treats
+ * them differently: an absent value falls back to our own backoff, while an
+ * explicit `0` is honoured as the server saying "immediately is fine".
+ */
+export function parseRetryAfterMs(headerValue, nowMs = Date.now()) {
+  if (headerValue == null) return null;
+  const raw = String(headerValue).trim();
+  if (raw === '') return null;
+
+  if (/^[+-]?\d+$/.test(raw)) {
+    const seconds = Number(raw);
+    // A negative delta-seconds is not "retry in the past", it is a malformed
+    // header. Guessing zero from it would hand the caller a no-wait retry,
+    // which is the exact behaviour this module exists to prevent.
+    if (seconds < 0) return null;
+    return Math.min(seconds * 1000, RATE_LIMIT_MAX_WAIT_MS);
+  }
+
+  // An HTTP-date always carries letters (a month name and a zone). Requiring
+  // one stops Date.parse from cheerfully interpreting stray numeric junk as a
+  // year and returning a confident, wrong timestamp.
+  if (!/[a-z]/i.test(raw)) return null;
+
+  const asDate = Date.parse(raw);
+  if (Number.isNaN(asDate)) return null;
+  // A date already in the past means "you may retry now", not "wait a negative
+  // amount of time" — clamp at zero rather than returning a nonsense delay.
+  return Math.min(Math.max(asDate - nowMs, 0), RATE_LIMIT_MAX_WAIT_MS);
+}
+
+/**
+ * How long to wait before attempt N+1.
+ *
+ * `retryAfterMs` can only ever RAISE the wait. A server that says "try again in
+ * 1ms" does not get to override our backoff — trusting the throttler about how
+ * fast we may return is precisely what produced 428 requests per second.
+ */
+export function rateLimitDelayMs(attempt, retryAfterMs, rng = Math.random) {
+  const exponential = BASE_DELAY_MS * 2 ** Math.max(0, attempt - 1);
+  // Jitter spreads a fleet of workers that were all refused in the same second,
+  // so they do not return in the same second either. It is injectable because a
+  // non-deterministic delay is otherwise untestable, and an untestable backoff
+  // is how a floor silently stops being a floor.
+  const jittered = exponential + Math.floor(rng() * BASE_DELAY_MS);
+  const own = Math.min(jittered, RATE_LIMIT_MAX_WAIT_MS);
+  if (typeof retryAfterMs !== 'number' || Number.isNaN(retryAfterMs)) return own;
+  return Math.min(Math.max(own, retryAfterMs), RATE_LIMIT_MAX_WAIT_MS);
+}
+
+/** Render a wait as something a person or a model reads without ambiguity. */
+function describeWait(retryAfterMs) {
+  if (typeof retryAfterMs !== 'number' || Number.isNaN(retryAfterMs) || retryAfterMs <= 0) {
+    return 'at least a minute';
+  }
+  const seconds = Math.max(1, Math.round(retryAfterMs / 1000));
+  return `${seconds}s`;
+}
+
+/**
+ * The message thrown once the retry budget is spent.
+ *
+ * This string is the actual fix. It has to do three things the old generic
+ * message did not: say the words "rate limit" so the failure is not mistaken
+ * for a transient error, say how long to wait, and say plainly not to retry
+ * immediately — because the caller is frequently a language model, and a model
+ * reading an opaque failure on a must-succeed operation will try again.
+ */
+export function describeRateLimit({ method, path, attempts, retryAfterMs }) {
+  return [
+    `Rate limited (HTTP 429) by the Adrata API on ${method} ${path}.`,
+    `Already retried with backoff ${attempts} times; the limit is still in force.`,
+    '',
+    `DO NOT retry this call immediately. Wait ${describeWait(retryAfterMs)} before trying again,`,
+    'or hand the work back and let a later pass pick it up.',
+    '',
+    'Retrying a 429 without waiting is what produced 7,059,080 rejected requests against',
+    'production on 2026-09-02 — one client repeating the same few lease releases tens of',
+    'thousands of times each. If this call is a worker-lease release, note that the lease',
+    'will expire on its own; a stuck release does not require a hot loop to resolve.',
+  ].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrata/adrata-mcp",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Adrata MCP Server \u2014 connect Claude Code, Codex, Gemini, Cursor, and other AI tools to your CRM. 80+ tools for companies, people, deals, actions, buyer groups, warm intros, webhooks, intelligence, and more.",
   "type": "module",
   "main": "server.js",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "start": "node server.js",
-    "test": "node --test analytics.test.js server.test.js api-bridge.test.js edge-block.test.js audit-flush.test.js buyer-group-writes.test.js note-writes.test.js mcp-spec.test.js packaging.test.js product-profile.test.js security.test.js tool-annotations.test.js toolsets.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js scripts/local-dev-server.test.js tools/competitive-coverage.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js tools/work-hub/audit.test.js tools/roadmap-tools.test.js tools/source-control/connection-tools.test.js governance/money.test.js"
+    "test": "node --test analytics.test.js server.test.js api-bridge.test.js http/edge-block.test.js http/rate-limit.test.js audit-flush.test.js buyer-group-writes.test.js note-writes.test.js mcp-spec.test.js packaging.test.js product-profile.test.js security.test.js tool-annotations.test.js toolsets.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js scripts/local-dev-server.test.js tools/competitive-coverage.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js tools/work-hub/audit.test.js tools/roadmap-tools.test.js tools/source-control/connection-tools.test.js governance/money.test.js"
   },
   "keywords": [
     "mcp",
@@ -42,9 +42,9 @@
   "files": [
     "server.js",
     "api-bridge.js",
+    "http/",
     "analytics.js",
     "security.js",
-    "edge-block.js",
     "transport-http.js",
     "resources.js",
     "tool-annotations.js",

package/product-profile.js

@@ -1,8 +1,8 @@
 /** Branded MCP launch profiles over one shared server implementation. */
 export const PRODUCT_PROFILES = Object.freeze({
   adrata: Object.freeze({ displayName: 'Adrata', domains: null }),
-  bounce: Object.freeze({
-    displayName: 'Bounce',
+  oasis: Object.freeze({
+    displayName: 'Oasis',
     domains: Object.freeze([
       'actions', 'agent', 'bridge', 'calendar', 'email', 'infra',
       'meetings', 'sequences', 'webhooks',

package/server.js

@@ -42,7 +42,13 @@ import {
 import { TIERS } from './access/tiers.js';
 import { findCompany, findPerson } from './tools/free-search.js';
 import { applySecurityLayer } from './security.js';
-import { describeEdgeBlock } from './edge-block.js';
+import { describeEdgeBlock } from './http/edge-block.js';
+import {
+  parseRetryAfterMs,
+  rateLimitDelayMs,
+  describeRateLimit,
+  RATE_LIMIT_MAX_ATTEMPTS,
+} from './http/rate-limit.js';
 import { registerMemoryTools, wrapWithEventLogging, registerProfileResource } from './tools/memory.js';
 import { registerBillingTools } from './tools/billing.js';
 import { registerMorningBrief } from './tools/morning-brief.js';
@@ -213,6 +219,28 @@ async function api(method, path, { params, body, headers: extraHeaders } = {}) {
     res = await request(currentToken);
   }
 
+  // A 429 used to fall straight through to the generic error below, which
+  // never said "rate limit" and never said how long to wait. Callers therefore
+  // read it as transient and retried immediately — 7,059,080 rejected requests
+  // against production on 2026-09-02. Wait, retry a bounded number of times,
+  // and if the limit still holds, fail with a message that says so. See
+  // rate-limit.js for the measured incident.
+  let rateLimitAttempts = 1;
+  let retryAfterMs = null;
+  while (res.status === 429 && rateLimitAttempts < RATE_LIMIT_MAX_ATTEMPTS) {
+    retryAfterMs = parseRetryAfterMs(res.headers.get('retry-after'));
+    const waitMs = rateLimitDelayMs(rateLimitAttempts, retryAfterMs);
+    await new Promise((resolve) => setTimeout(resolve, waitMs));
+    rateLimitAttempts += 1;
+    res = await request(currentToken);
+  }
+  if (res.status === 429) {
+    retryAfterMs = parseRetryAfterMs(res.headers.get('retry-after')) ?? retryAfterMs;
+    throw new Error(
+      describeRateLimit({ method, path, attempts: rateLimitAttempts, retryAfterMs }),
+    );
+  }
+
   const text = await res.text();
   let data;
   try { data = JSON.parse(text); } catch { data = { raw: text }; }
@@ -527,8 +555,15 @@ server.tool('workspace_status',
     return ok({
       connected: AUTH.authenticated,
       tier: AUTH.tier,
-      credential: CREDENTIALS[AUTH.source] ?? AUTH.source,
+      // Name the opt-in explicitly. Whether this process is acting as its own
+      // api_key actor or as the machine-wide shared human session is the whole
+      // question a fleet lane runs this tool to answer, and both report
+      // `source: 'api_key'`-adjacent states that look alike from outside.
+      credential: AUTH.preferredApiKey
+        ? 'ADRATA_API_KEY (environment), preferred over any on-disk session by ADRATA_MCP_PREFER_API_KEY'
+        : CREDENTIALS[AUTH.source] ?? AUTH.source,
       authSource: AUTH.source,
+      preferredApiKey: Boolean(AUTH.preferredApiKey),
       apiBase: API_BASE,
       workspaceId,
       workspaceName,

package/server.json

@@ -3,7 +3,7 @@
   "name": "com.adrata/adrata-mcp",
   "description": "Adrata revenue-intelligence MCP server: companies, people, opportunities, actions, buyer groups, enrichment, email, and workspace operations for AI agents.",
   "status": "active",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "websiteUrl": "https://adrata.com/developers",
   "repository": {
     "url": "https://github.com/adrata/adrata",
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@adrata/adrata-mcp",
-      "version": "1.0.7",
+      "version": "1.0.8",
       "transport": {
         "type": "stdio"
       },

package/tool-annotations.js

@@ -241,7 +241,14 @@ const IDEMPOTENT_WRITES = new Set([
   // comment, criterion, or card.
   'move_work_item', 'transfer_work_item_between_boards', 'set_work_board_column_wip_limit', 'set_work_item_tag', 'set_work_item_kind',
   'create_work_item', 'comment_on_work_item', 'flag_work_item',
+  // A repeat block is the same edge (the pair is unique), and a repeat
+  // unblock deletes a row that is already gone. Neither compounds.
+  'block_work_item', 'unblock_work_item',
   'add_work_item_acceptance_criterion',
+  // Reclassifying is a PUT of the whole routing decision, not an append:
+  // replaying the same key rewrites the criterion to the same route and the
+  // server's receipt table records one change, never a second one.
+  'classify_work_item_acceptance_criterion',
   // Ticking and un-ticking are both genuinely idempotent, and for different
   // reasons worth keeping straight: a repeat tick is a no-op because the server
   // only writes the ticker, column and note where they were empty, and a repeat

package/tools/work-board-tools.js

@@ -371,7 +371,7 @@ export function registerWorkBoardTools(
 
   server.tool(
     'list_my_work_items',
-    `The cards that are YOURS, across every board in the workspace, ordered the way a developer actually picks: escalated first (the top band of each card's OWN scheme — a P1 is never equated with a Critical), then by the board's own left-to-right flow so the earliest active stage comes first, then longest-waiting. Cards in a terminal column (Production, Deep backlog) sink to the bottom, because nothing should be picked up from them.
+    `The cards that are YOURS, across every board in the workspace, ordered the way a developer actually picks: parked cards last (Deep backlog is where work was deliberately shelved, and offering it back argues with whoever parked it), then escalated first (the top band of each card's OWN scheme — a P1 is never equated with a Critical), then by the board's own left-to-right flow so the earliest active stage comes first, then longest-waiting. Production sits at the end of that flow, so nothing is picked up from it either.
 
 "Yours" is TWO things: cards you OWN (you are the assignee, carrying it end to end) and cards whose CURRENT PASS you hold (you took it at a stage — the QA case). Both appear here, and each card carries assignee and handler so you can tell which of the two put it in front of you. A QA person owns none of the cards they are testing, so a queue keyed only on the assignee would tell them they had no work while four cards sat on their bench.
 
@@ -553,7 +553,7 @@ Start here for "what should I work on". With includeUnassigned it also returns t
 
   server.tool(
     'claim_next_work_item_qa_pass',
-    `Atomically choose and take the first workable QA pass for ONE exact product in ONE requested gate across every board this worker can see. Product is read from the card, never inferred from the board that happens to hold it. QA1 and QA2 pools must name their gate explicitly; a QA1 drain can never consume QA2 work and vice versa. Concurrent sessions receive distinct cards; one MCP worker holds at most one pass at a time. An empty result means no eligible pass remains in that product/gate. The response returns the selected board and card, explains the selection, and carries the exact acceptance criteria and recorded-QA requirements. Capability material stays inside this MCP process.${GOVERNED_NOTE}`,
+    `Atomically choose and take the first workable QA pass for ONE exact product in ONE requested gate across every board this worker can see. Product is read from the card, never inferred from the board that happens to hold it. QA1 and QA2 pools must name their gate explicitly; a QA1 drain can never consume QA2 work and vice versa. Concurrent sessions receive distinct cards; one MCP worker holds at most one pass at a time. An empty result is TWO different situations and the response tells them apart: an empty skippedBlocked means no eligible pass remains in that product/gate, so move to another lane; a non-empty skippedBlocked means there IS work here and every card is waiting on another card, so read the blockers rather than re-claiming. The response returns the selected board and card, explains the selection, and carries the exact acceptance criteria and recorded-QA requirements. Capability material stays inside this MCP process.${GOVERNED_NOTE}`,
     {
       qaGate: z.enum(['Staging QA1', 'Staging QA2']).describe('Exact gate this worker pool is allowed to drain.'),
       product: z.string().min(1).max(120).describe('Exact card product to drain, such as Adrata or Starfield, across all visible boards.'),
@@ -604,13 +604,30 @@ Start here for "what should I work on". With includeUnassigned it also returns t
         body,
         headers: buildMutationHeaders(args),
       });
-      const selected = data?.data;
+      // The route answers with an OUTCOME, not a bare card: `claimed` may be
+      // null while `skippedBlocked` explains why. Reading `data.data` as the
+      // card directly would silently produce an undefined workItemId.
+      const outcome = data?.data ?? {};
+      const selected = outcome.claimed;
+      const skippedBlocked = outcome.skippedBlocked ?? [];
       if (!selected) {
-        return ok({ claimed: false, qaGate: args.qaGate, product: args.product, note: `No eligible unclaimed ${args.product} ${args.qaGate} pass remains on any visible board.` });
+        // The empty-handed case is two different situations and a lane acts on
+        // them differently: an empty gate means pick another lane, while a
+        // fully-blocked one means go and look at the blockers.
+        return ok({
+          claimed: false,
+          qaGate: args.qaGate,
+          product: args.product,
+          skippedBlocked,
+          note: skippedBlocked.length
+            ? `No workable ${args.product} ${args.qaGate} pass remains: ${skippedBlocked.length} card(s) in this gate are blocked by another card. Do not re-claim — look at the blockers listed in skippedBlocked.`
+            : `No eligible unclaimed ${args.product} ${args.qaGate} pass remains on any visible board.`,
+        });
       }
       const visible = rememberWorkerLease(selected.workItemId, selected.grant, args.idempotencyKey);
       return ok({
         claimed: true,
+        skippedBlocked,
         workItemId: selected.workItemId,
         boardId: selected.boardId,
         boardName: selected.boardName,
@@ -1589,6 +1606,106 @@ QA PASSES ARE THE EXCEPTION. An executable QA worker must hold the process-priva
     }
   );
 
+  server.tool(
+    'block_work_item',
+    `Record that one card CANNOT START until another lands. Use this for a real dependency — the fix that has to ship first, the fixture the test needs, the decision the work waits on — not for a note or a "related to". A recorded dependency changes what the queue hands out: a blocked card stops being offered as workable to a lane, and is instead shown with the blocker named, so the next agent does not pay a full read-and-release to rediscover it.
+
+Reading direction is "itemId is blocked by blockedByItemId".
+
+The blocker resolves ON ITS OWN when it reaches Ready to Ship or Production — there is nothing to unset, and no "resolved" flag to keep in step. A blocker parked in Backlog or Deep backlog still blocks, and the queue says so in those words, because that case needs an owner decision rather than a retry.
+
+Cross-BOARD links are allowed (a CRO card blocked by a Starfield defect is the case this exists for). A cycle is refused: if the blocker already depends on this card, directly or through others, the write returns 409 rather than creating a loop in which no card could ever be started.
+
+This says "do not start this yet". It NEVER says "this is already proved" — a dependency does not satisfy an acceptance criterion, and QA evidence is never inherited across a link.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('The card that cannot start.'),
+      blockedByItemId: z.string().describe('The card it is waiting on.'),
+      reason: z
+        .string()
+        .describe('Why this dependency is real, in a sentence. Required — this is what the next agent reads instead of re-deriving it.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live change.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      idempotencyKey: z.string().optional().describe('Required for a live change.'),
+    },
+    async (args) => {
+      if (args.itemId === args.blockedByItemId) {
+        return ok({
+          error: true,
+          message: 'A card cannot block itself.',
+        });
+      }
+
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/dependencies`;
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldBlock: {
+            itemId: args.itemId,
+            blockedByItemId: args.blockedByItemId,
+            reason: args.reason,
+          },
+        });
+      }
+
+      const data = await api('POST', path, {
+        body: {
+          blockedByItemId: args.blockedByItemId,
+          reason: args.reason,
+          idempotencyKey: args.idempotencyKey,
+        },
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ blocked: true, itemId: args.itemId, blockedBy: data?.data });
+    }
+  );
+
+  server.tool(
+    'unblock_work_item',
+    `Remove a dependency that should not have been recorded — a link added in error, or one that turned out not to be real.
+
+This is NOT how a dependency ends in the normal course. A blocker resolves by REACHING Ready to Ship or Production, which the queue derives on its own; deleting the edge instead would say the dependency never existed and lose why the card waited. Use this only to correct the record.
+
+Removing an edge that is not there succeeds: the caller asked for a state, and that state is what they get.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('The blocked card.'),
+      blockedByItemId: z.string().describe('The blocker to unlink.'),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false for a live change.'),
+      approved: z.boolean().optional().describe('Required true for a live change.'),
+      reason: z.string().optional().describe('Required for a live change: why this link was wrong.'),
+      idempotencyKey: z.string().optional().describe('Required for a live change.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/dependencies/${encodeURIComponent(args.blockedByItemId)}`;
+      const preview = validateApiBridgeRequest({
+        method: 'DELETE',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldUnblock: { itemId: args.itemId, blockedByItemId: args.blockedByItemId },
+        });
+      }
+
+      const data = await api('DELETE', path, { headers: buildMutationHeaders(args) });
+      return ok({ unblocked: true, itemId: args.itemId, blockedBy: data?.data });
+    }
+  );
+
   server.tool(
     'set_work_item_tag',
     `Set a card's URGENCY tag. The scheme must be one the board reads (severity | priority | impact) and the source must be human, model, or rules. A "model" tag REQUIRES a confidence: the board drops a low-confidence model tag, and a model tag with no confidence cannot be held to that floor, so it would be trusted by default — backwards. This does NOT say what kind of work the card is — that is a separate field; use set_work_item_kind, and note that setting one never disturbs the other.${GOVERNED_NOTE}`,
@@ -1917,6 +2034,84 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
     }
   );
 
+  server.tool(
+    'classify_work_item_acceptance_criterion',
+    `Change WHICH KIND OF PROOF one existing acceptance criterion needs, and record who decided. Use this when a criterion is routed \`product\` but a signed-in browser could not establish it AT ALL — its \`thenText\` is about a test suite, a named source file, a migration receipt, an ECS task definition, a CI leg, an HTTP status contract, a log record or a vendor invoice. A criterion routed \`product\` by mistake is not merely mislabelled: it demands a recording of something that has no screen, so it can never legitimately pass, and the QA lane that draws it spends a whole pass discovering that.
+
+THIS IS NOT A WAIVER, AND THE ASYMMETRY IS THE POINT. \`engineering\` asks a reviewer for MORE than \`product\`, not less — an exact deployed build SHA, named executed code/test/configuration/runtime references, and a reviewer independent of the author (see record_work_item_criterion_engineering_proof). \`both\` requires BOTH and is the STRICTEST of the three. What \`engineering\` drops is the one demand that was never satisfiable: a browser replay of a thing that has no rendered surface. Both QA gates still run either way, and no route changes whether a criterion has been proved — only what would count as proving it.
+
+SO ROUTE FROM THE CRITERION'S OWN WORDS, NOT FROM WHAT IS CHEAP TODAY. Can a browser DISPLAY the result its \`thenText\` asks for? Then it is \`product\` and it stays \`product\`. A fixture you do not have, an environment that is down, or a journey that is tedious to record are reasons to report a blocker, never reasons to reclassify. If the criterion carries a code fact AND a seller-visible outcome it is \`both\`, or leave it \`product\`; quietly splitting that difference downward is the one thing this tool could be used to launder.
+
+\`engineeringReason\` is REQUIRED for \`engineering\` and \`both\` and REFUSED for \`product\`: say in plain language why no meaningful product-person retest exists, because a later reader has to trust the routing rather than re-derive it. \`note\` is the separate audit sentence for THIS act — why the classification is changing now.
+
+The server refuses the change when the card is standing at a QA gate AND you are the credential that wrote the criterion, in the direction that adds the engineering claim or drops the product one. That is deliberate: reclassifying your own check out of the recording a reviewer just asked for is the exact move the rule exists to stop. Ask the reviewer to reclassify it, or say why on the card. Classification belongs at grooming. Every change writes a durable receipt carrying the previous route, the new one, both sentences, your credential, and the column and dwell the card was standing in.${GOVERNED_NOTE}`,
+    {
+      itemId: z.string().describe('Card id.'),
+      criterionId: z
+        .string()
+        .describe(
+          'Criterion id from list_work_item_acceptance_criteria — the `id`, not the `ordinal`.'
+        ),
+      verificationRoute: z
+        .enum(['product', 'engineering', 'both'])
+        .describe(
+          'REQUIRED. The route this criterion should have had. `product` needs a ' +
+          'signed-in browser recording; `engineering` needs executed ' +
+          'code/test/runtime proof against an exact build; `both` needs BOTH ' +
+          'and is the STRICTEST of the three, not a compromise.'
+        ),
+      engineeringReason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for engineering or both, refused for product: why no meaningful ' +
+          'product-person retest exists. Plain language, 600 characters or fewer.'
+        ),
+      note: z
+        .string()
+        .optional()
+        .describe(
+          'Why the classification is changing NOW — the audit note for this one act, ' +
+          'distinct from engineeringReason, which is the standing claim about the criterion.'
+        ),
+      dryRun: z.boolean().optional().describe('Defaults to true. Set false to apply it.'),
+      approved: z.boolean().optional().describe('Required true for a live write.'),
+      reason: z
+        .string()
+        .optional()
+        .describe('Required for a live write: why this criterion is being reclassified.'),
+      idempotencyKey: z.string().optional().describe('Required for a live write. Reuse on retry.'),
+    },
+    async (args) => {
+      const path = `/api/v1/work-items/${encodeURIComponent(args.itemId)}/acceptance-criteria/${encodeURIComponent(args.criterionId)}/verification-route`;
+      const preview = validateApiBridgeRequest({
+        method: 'PUT',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      const classification = {
+        verificationRoute: args.verificationRoute,
+        engineeringReason: args.engineeringReason,
+        note: args.note,
+      };
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldClassify: { itemId: args.itemId, criterionId: args.criterionId, classification },
+        });
+      }
+      const data = await api('PUT', path, {
+        body: classification,
+        headers: buildMutationHeaders(args),
+      });
+      return ok({ classified: true, criterion: data?.data });
+    }
+  );
+
   server.tool(
     'satisfy_work_item_acceptance_criterion',
     `Tick one acceptance criterion with the evidence you actually observed.
@@ -2299,10 +2494,13 @@ export const WORK_BOARD_TOOL_NAMES = [
   'set_work_item_kind',
   'create_work_item',
   'add_work_item_acceptance_criterion',
+  'classify_work_item_acceptance_criterion',
   'satisfy_work_item_acceptance_criterion',
   'record_work_item_criterion_engineering_proof',
   'unsatisfy_work_item_acceptance_criterion',
   'get_work_item_comments',
   'comment_on_work_item',
   'flag_work_item',
+  'block_work_item',
+  'unblock_work_item',
 ];