@adrata/adrata-mcp 1.0.6 → 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/edge-block.js

@@ -0,0 +1,118 @@
+/**
+ * Tell an edge block apart from an authorization failure.
+ *
+ * The problem this exists for. api.adrata.com resolves to the ALB directly, and
+ * an AWS WAF web ACL sits on that ALB. When a managed rule matches a REQUEST
+ * BODY the request is refused at the edge and never reaches the Rust API, so
+ * the caller gets a bare HTML page:
+ *
+ *     <html>
+ *     <head><title>403 Forbidden</title></head>
+ *     <body>
+ *     <center><h1>403 Forbidden</h1></center>
+ *     </body>
+ *     </html>
+ *
+ * 403 is also what the API returns for a genuine `insufficient_scope`. Nothing
+ * in the old error message distinguished them, so the reasonable conclusion was
+ * "my token lost board write access" — and the reasonable next step was to ask
+ * the owner to reconnect the workspace. That reconnect loop has been run more
+ * than once for a cause that had nothing to do with credentials.
+ *
+ * The tell is decisive and needs no guessing. The Adrata API serialises EVERY
+ * error through one `IntoResponse` impl that always emits a JSON envelope
+ * (`code/api/crates/core/src/error.rs`), and its fallback route is JSON-only.
+ * An HTML body from this host is therefore structurally impossible to have come
+ * from the application. Something in front of it answered.
+ *
+ * Measured 2026-08-29 against production, same endpoint, same session, same
+ * everything but the body text:
+ *
+ *     plain prose ....................... 404 JSON  (reached the app)
+ *     markdown table, pipes only ........ 404 JSON  (reached the app)
+ *     fenced code block, backticks ...... 404 JSON  (reached the app)
+ *     JSX with angle brackets ........... 404 JSON  (reached the app)
+ *     "aaa ../ bbb" ..................... 403 HTML  (refused at the edge)
+ *     "link:../../packages/..." ......... 403 HTML  (refused at the edge)
+ *     "the file /etc/passwd is not read"  404 JSON  (reached the app)
+ *
+ * So the trigger is the path-traversal token `../`, not markdown structure —
+ * which matters, because "avoid tables and code fences" is the wrong lesson and
+ * would quietly strip evidence out of bug reports for no reason.
+ */
+
+/** Substrings measured to be refused at the edge, most specific first. */
+const MEASURED_TRIGGERS = [
+  { pattern: '../', label: 'a relative path segment (`../`)' },
+  { pattern: '..\\', label: 'a Windows relative path segment (`..\\`)' },
+  { pattern: '..%2f', label: 'a percent-encoded path segment (`..%2f`)' },
+  { pattern: '..%5c', label: 'a percent-encoded path segment (`..%5c`)' },
+];
+
+/**
+ * True when a response body cannot have come from the Adrata API.
+ *
+ * Deliberately narrow. It looks for an HTML document rather than for "not
+ * JSON": an empty body, a timeout, or a truncated read are different failures
+ * and must not be reported as an edge block.
+ */
+export function looksLikeEdgeHtml(text) {
+  if (typeof text !== 'string') return false;
+  const head = text.trimStart().slice(0, 400).toLowerCase();
+  if (!head.startsWith('<html') && !head.startsWith('<!doctype html')) return false;
+  return head.includes('<title>') || head.includes('<h1>');
+}
+
+/**
+ * Name the content the edge is most likely to have objected to.
+ *
+ * Returns every measured trigger present, because a body often carries more
+ * than one and fixing only the first sends the caller round again. Unknown is
+ * reported as unknown: a body with no measured trigger returns an empty list
+ * rather than a guess, so the caller is never told to edit the wrong sentence.
+ */
+export function offendingContent(requestBody) {
+  if (requestBody == null) return [];
+  let serialized;
+  try {
+    serialized = typeof requestBody === 'string' ? requestBody : JSON.stringify(requestBody);
+  } catch {
+    return [];
+  }
+  if (typeof serialized !== 'string') return [];
+  const haystack = serialized.toLowerCase();
+  return MEASURED_TRIGGERS.filter(({ pattern }) => haystack.includes(pattern)).map(
+    ({ label }) => label
+  );
+}
+
+/**
+ * Build the message for a request the edge refused, or return null when this
+ * was an ordinary API error and the caller should report it unchanged.
+ */
+export function describeEdgeBlock({ status, text, method, path, requestBody } = {}) {
+  if (!looksLikeEdgeHtml(text)) return null;
+  if (typeof status !== 'number' || status < 400 || status > 499) return null;
+
+  const found = offendingContent(requestBody);
+  const because = found.length
+    ? `The request body contains ${found.join(' and ')}, which the edge's path-traversal rule matches.`
+    : 'No known trigger was found in this request body, so the matching rule is not one already measured. Report the request id and the body, and check the WAF sampled requests.';
+
+  return [
+    `API ${method} ${path} → ${status}, refused at the network edge before it reached Adrata.`,
+    '',
+    'This is NOT an authentication or scope failure, and reconnecting the workspace will not',
+    'change it. The proof is the response body: the Adrata API serialises every error as JSON,',
+    'so an HTML error page from this host was produced by something in front of it (an AWS WAF',
+    'managed rule on the ALB). Your session is unaffected — do not call connect_workspace, and',
+    'do not ask the owner to reconnect.',
+    '',
+    because,
+    '',
+    'What to do: rewrite the offending text and resend. A relative path reads the same as',
+    '`code/desktop` or `<repo root>/packages/client-runtime`, and the record is no worse for it.',
+    'Do NOT strip out markdown tables or fenced code blocks — those were measured to pass, and',
+    'removing them only makes the record vaguer.',
+  ].join('\n');
+}

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.6",
+  "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 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,6 +42,7 @@
   "files": [
     "server.js",
     "api-bridge.js",
+    "http/",
     "analytics.js",
     "security.js",
     "transport-http.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

@@ -31,6 +31,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { readFileSync } from 'node:fs';
 import {
   authenticate,
   reauthenticate,
@@ -41,6 +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 './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';
@@ -211,11 +219,45 @@ 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 }; }
 
   if (!res.ok) {
+    // An HTML body cannot have come from the API — every AppError serialises as
+    // JSON — so it means the request was refused in front of us. Saying so is
+    // the whole point: a bare 403 is indistinguishable from insufficient_scope,
+    // and reading it as a token problem is what starts a needless reconnect.
+    const edge = describeEdgeBlock({
+      status: res.status,
+      text,
+      method,
+      path,
+      requestBody: body,
+    });
+    if (edge) throw new Error(edge);
     throw new Error(`API ${method} ${path} → ${res.status}: ${JSON.stringify(data).slice(0, 200)}`);
   }
   return data;
@@ -299,9 +341,12 @@ const moneyWrite = {
  * to start, which is the exact failure this whole surface keeps producing.
  */
 const SERVER_NAME = process.env.ADRATA_MCP_SERVER_NAME?.trim() || '@adrata/adrata-mcp';
+const PACKAGE_VERSION = JSON.parse(
+  readFileSync(new URL('./package.json', import.meta.url), 'utf8')
+).version;
 
 function createMcpServer() {
-const server = new McpServer({ name: SERVER_NAME, version: '1.0.0' });
+const server = new McpServer({ name: SERVER_NAME, version: PACKAGE_VERSION });
 
 // ---------------------------------------------------------------------------
 // Tier-gating wrapper
@@ -510,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,
@@ -558,7 +610,7 @@ function assertProductCapability(capability, requested) {
 }
 
 async function resolveExactCapability(reference) {
-  const response = await api('GET', '/api/v1/ai/crm-tools/capabilities/describe', {
+  const response = await api('GET', '/api/v1/ai-crm-tools/capabilities/describe', {
     params: { ref: reference },
   });
   return assertProductCapability(response?.capability ?? response?.data?.capability, reference);
@@ -576,7 +628,7 @@ server.tool('search_capabilities',
     if (PRODUCT_NAMESPACE && requestedNamespace && requestedNamespace !== PRODUCT_NAMESPACE) {
       throw new Error(`${SERVER_NAME} search is fixed to the ${PRODUCT_NAMESPACE} namespace.`);
     }
-    return ok(await api('GET', '/api/v1/ai/crm-tools/capabilities/search', {
+    return ok(await api('GET', '/api/v1/ai-crm-tools/capabilities/search', {
       params: {
         q: args.query,
         namespace: PRODUCT_NAMESPACE || requestedNamespace,
@@ -618,7 +670,7 @@ server.tool('run_capability',
     if (args.idempotencyKey) headers['idempotency-key'] = args.idempotencyKey;
     if (args.reason) headers['x-adrata-reason'] = args.reason;
     if (args.confirmSpend === true) headers['x-adrata-approved'] = 'true';
-    return ok(await api('POST', '/api/v1/ai/crm-tools/execute', { body, headers }));
+    return ok(await api('POST', '/api/v1/ai-crm-tools/execute', { body, headers }));
   });
 
 server.tool('adrata_api_catalog',

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.6",
+  "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.6",
+      "version": "1.0.8",
       "transport": {
         "type": "stdio"
       },

package/skills/qa-the-card/SKILL.md

@@ -32,6 +32,14 @@ their operating procedure.
    be executable at the current gate. Add or correct missing coverage before
    calling the card clean; never turn a vague criterion green by interpreting it
    generously.
+5. Missing independent QA evidence by itself is expected at QA1 entry and never
+   justifies a bounce. Do not report a vague “missing evidence path”: name the
+   allegedly missing product route, fixture, credential, artifact location, or
+   current-dwell QA receipt, and resolve relative artifact paths against the
+   owning worktree or durable location before declaring them absent. If the
+   executable prerequisite truly is missing, keep the card in QA and run the
+   same-card fix-and-retest loop; if only the independent receipt is missing,
+   start the pass.
 
 ## Preserve independent gates
 
@@ -41,6 +49,27 @@ their operating procedure.
   credential whose clean receipt opened QA1. Never impersonate a human to bypass
   this rule. A human may perform the final acceptance even when they own or
   authored the card.
+- **Take that credential from a QA lane, and take a different one per
+  worktree.** Staging seeds twenty-four of them — `qa-lane-1@adrata.test`
+  through `qa-lane-24@adrata.test`, lanes 1-18 `admin` and 19-24 `seller`.
+  There are deliberately more lanes than the fleet can drive, so a tester
+  never queues behind an identity:
+
+  ```bash
+  node scripts/qa-staging-lane.mjs --list            # every lane and its role
+  node scripts/qa-staging-lane.mjs <lane> --write-env  # this worktree's tests/e2e/.env
+  ```
+
+  The rule above is unsatisfiable with one shared login, and the failure is
+  silent rather than loud: every recording is the same actor, so cards get
+  honestly CLAIMED and none can be legitimately VERIFIED. Sharing a lane
+  between two live agents is the same defect wearing a different hat — they
+  share a session, a workspace switch and a chat history, so one lane's
+  navigation lands in another lane's recording. Record the lane on the receipt,
+  so "a different credential" is a checkable claim rather than an assertion.
+  The accounts come from the non-production boot seed
+  (`code/api/crates/schema/src/seeds/non_prod.rs`) and exist only on staging
+  and local; they cannot be created in production.
 - For non-trivial QA2 work, use at least one independent adversarial reviewer
   when subagents are authorized and available. Parallelize separable surfaces
   such as UI, backend/security, and migration/deployment behavior. Give each
@@ -117,6 +146,16 @@ does not establish that the screen is visually correct.
 - Reopen both uploaded gate recordings before handoff. Prove each fresh
   short-lived URL loads and that each video can play, seek, and enter
   fullscreen; an upload response alone is not a media pass.
+- A staging QA lane and the canonical board may intentionally use separate data
+  planes. Do not copy a production card into staging, reuse the builder's browser
+  credential, or put an OAuth bearer or presigned media URL in the transcript.
+  Run `npm run --silent qa:canonical-card-review -- <card-id>` under the fresh
+  reviewer's named `ADRATA_MCP_IDENTITY_POOL` and dedicated
+  `ADRATA_MCP_CONFIG_DIR`. It opens the exact deployed product bundle through a
+  one-use, read-only loopback session: upstream reads keep the QA OAuth identity,
+  writes fail locally, and private media capabilities remain process-private.
+  Record the returned session fingerprint and the deployed app build in the
+  playback evidence, then close the bridge.
 
 ## Manage cards as outcomes, not bug counters
 

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

@@ -5,6 +5,11 @@ import { basename, resolve } from 'node:path';
 
 const MAX_QA_IMAGE_BYTES = 10 * 1024 * 1024;
 const MAX_QA_VIDEO_BYTES = 100 * 1024 * 1024;
+const QA_STAGE_NAMES = new Set(['staging qa1', 'staging qa2']);
+
+function isQaStageName(name) {
+  return QA_STAGE_NAMES.has(String(name ?? '').trim().toLowerCase());
+}
 
 /** Read evidence bytes locally without ever putting them in the MCP transcript. */
 export async function loadLocalQaEvidenceFile(filePath) {
@@ -178,6 +183,45 @@ export function describeMissingAcceptanceCriteria(criteria) {
   return 'This card would have no executable acceptance criteria. It can be captured, but it is not ready for build or QA until at least one where/when/then criterion is added.';
 }
 
+/**
+ * Make the created card's own criteria counter agree with the criteria returned
+ * beside it.
+ *
+ * Criteria are written by a second call, AFTER `POST /items` has already
+ * answered. So the card snapshot in that answer was serialized before the rows
+ * existed and its derived `criteria.total` reads 0 — while the array a few
+ * lines below it in the same response holds the rows that were just committed.
+ * Two fields of one response, disagreeing.
+ *
+ * That is not cosmetic. An agent reading `item.criteria.total` from a create it
+ * just made concludes the card has NO executable definition of done, at exactly
+ * the moment the board exists to prevent that, and then either reports the card
+ * as not ready for build or re-adds criteria that already exist. The correct
+ * data is in the same response a few lines lower, which is what makes it
+ * invisible.
+ *
+ * The repair is a fresh read of the card rather than a locally patched number,
+ * because the counter is derived server-side and the server is the only party
+ * that can state it. The read is skipped entirely when no criteria were written
+ * — there is no stale counter to repair, and the create path should not spend a
+ * request proving that.
+ *
+ * A failed read-back must NOT turn a create that succeeded into an error: the
+ * card and its criteria are on the record either way. In that one case the
+ * count is reconciled from the rows this function is holding, which is a fact it
+ * already has rather than a guess.
+ */
+export async function reconcileCriteriaCount(api, item, criteria) {
+  if (!item?.id || criteria.length === 0) return item;
+  try {
+    const fresh = await api('GET', `/api/v1/work-items/${encodeURIComponent(item.id)}`);
+    if (fresh?.data?.criteria) return fresh.data;
+  } catch {
+    // Fall through to the local reconciliation below.
+  }
+  return { ...item, criteria: { ...(item.criteria ?? {}), total: criteria.length } };
+}
+
 /**
  * The satisfaction sub-resource of one criterion, POSTed to tick and DELETEd to
  * un-tick.
@@ -327,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.
 
@@ -509,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.'),
@@ -560,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,
@@ -1189,11 +1250,11 @@ Start here for "what should I work on". With includeUnassigned it also returns t
 
   server.tool(
     'move_work_item',
-    `Move a card to another column on the same board — and, with claim:true, pick it up in the same action. The server does this in ONE transaction: it closes the card's open dwell, appends the transition to the history, records you as the handler of the pass the card is now on, and updates the card. Dropping a card into the column it is already in is a REORDER and deliberately does not restamp the stage timer.
+    `Move a card to another column on the same board — and, outside QA, use claim:true to pick it up in the same action. The server does this in ONE transaction: it closes the card's open dwell, appends the transition to the history, records you as the handler of the pass the card is now on, and updates the card. Dropping a card into the column it is already in is a REORDER and deliberately does not restamp the stage timer.
 
 A card carries TWO people and they are not interchangeable. The OWNER (assignee) is whoever carries the card end to end — the engineer who builds it, and the person a QA bounce sends it back to. The HANDLER is whoever took the pass the card is on right now, which at a QA gate is the tester and nowhere else is usually the owner. claim:true always takes the pass; it takes ownership ONLY of a card nobody owns. So a QA pick-up on an engineer's card leaves the engineer owning it, which is what makes the two-gate flow work at all.
 
-This is both halves of the developer loop. Claiming is a parameter and not a second tool on purpose: picking a card up is one act, and a separate "assign" call is the one that gets skipped — leaving a card in an active column with no owner, which is the exact finding the board's unassigned glyph exists to shout about.${GOVERNED_NOTE}`,
+QA PASSES ARE THE EXCEPTION. An executable QA worker must hold the process-private lease and fencing capability before it can write in Staging QA1 or Staging QA2. Use claim_work_item_qa_pass (or claim_next_work_item_qa_pass) after the card is in QA; never use move_work_item(claim:true) to take a QA pass. This connector refuses that legacy shape locally instead of sending an unfenced write the API must reject.${GOVERNED_NOTE}`,
     {
       itemId: z.string().describe('Card id to move.'),
       toColumnId: z
@@ -1209,7 +1270,7 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         .boolean()
         .optional()
         .describe(
-          'Pick this card up as part of this move: it records YOU as the handler of the pass the card lands on, and makes you the owner only if the card has no owner. "You" is resolved from the authenticated token — there is no way to claim on somebody else\'s behalf. Use it whenever you are picking work up. Taking a pass on a card SOMEBODY ELSE OWNS is allowed and normal (that is a QA pick-up) and leaves their ownership alone; taking a pass somebody else is already HOLDING is refused (see force). Re-claiming a pass you already hold is a no-op, not an error. The handler is written to the card\'s open dwell, so a same-column claim works too — that is how you take a pass on a card already sitting in your stage.'
+          'Pick this card up as part of a NON-QA move: it records YOU as the handler of the pass the card lands on, and makes you the owner only if the card has no owner. "You" is resolved from the authenticated token — there is no way to claim on somebody else\'s behalf. Staging QA1 and Staging QA2 use claim_work_item_qa_pass instead because every executable QA write must carry a process-private lease and fence. Taking a non-QA pass somebody else is already HOLDING is refused (see force). Re-claiming a non-QA pass you already hold is a no-op, not an error.'
         ),
       force: z
         .boolean()
@@ -1229,6 +1290,12 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         .string()
         .optional()
         .describe('Required for a live move. Reuse the SAME key on retry; the server replays.'),
+      acknowledgeUnmetCriteria: z
+        .boolean()
+        .optional()
+        .describe(
+          'Record an explicit override for moving a card FORWARD out of Staging QA1 or Staging QA2 with acceptance criteria still unverified. The first such move is always refused (409) naming what is open; sending this is the acknowledgement itself, and the server stores the count on the transition row where a release review reads it later. IT IS A HUMAN ACT: the API refuses it to a program (403) before it reads the flag, so an agent setting it gets a refusal rather than a waiver. It is also NOT how a card gets parked — moving a card to Backlog or Deep backlog is a different kind of move and needs no override at all.'
+        ),
       receipt: z
         .object({
           commitSha: z
@@ -1314,6 +1381,18 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         const count = (board.items ?? []).filter(
           (candidate) => candidate.columnId === args.toColumnId
         ).length;
+        if (args.claim === true && isQaStageName(target.name)) {
+          return ok({
+            ...preview,
+            blocked: true,
+            code: 'qa_pass_requires_worker_lease_claim',
+            message:
+              item.columnId === args.toColumnId
+                ? `Card ${args.itemId} is already in ${target.name}. Use claim_work_item_qa_pass to take this exact QA dwell atomically; move_work_item cannot create or retain the required private lease fence.`
+                : `Move card ${args.itemId} into ${target.name} without claim:true, then use claim_work_item_qa_pass to take the new QA dwell atomically. move_work_item cannot create or retain the required private lease fence.`,
+            wouldSend: false,
+          });
+        }
         return ok({
           ...preview,
           wouldMove: {
@@ -1333,6 +1412,33 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
         });
       }
 
+      // The generic move claim predates executable QA worker leases. It can
+      // name a handler, but it cannot return and retain the bearer/fence that
+      // every later agent write in a QA dwell must prove. Sending that legacy
+      // shape now produces an opaque 409 and leaves no claimed pass. Resolve
+      // the target before the mutation and direct the worker to the dedicated
+      // atomic lease endpoint instead. The API fence remains mandatory.
+      if (args.claim === true) {
+        const itemData = await api('GET', `/api/v1/work-items/${encodeURIComponent(args.itemId)}`);
+        const item = itemData?.data;
+        const boardData = item?.boardId
+          ? await api('GET', `/api/v1/work-boards/${encodeURIComponent(item.boardId)}`)
+          : null;
+        const target = boardData?.data?.columns?.find(
+          (column) => column.id === args.toColumnId
+        );
+        if (isQaStageName(target?.name)) {
+          return ok({
+            error: true,
+            code: 'qa_pass_requires_worker_lease_claim',
+            message:
+              item?.columnId === args.toColumnId
+                ? `Card ${args.itemId} is already in ${target.name}. Use claim_work_item_qa_pass to take this exact QA dwell atomically; move_work_item cannot create or retain the required private lease fence.`
+                : `Move card ${args.itemId} into ${target.name} without claim:true, then use claim_work_item_qa_pass to take the new QA dwell atomically. move_work_item cannot create or retain the required private lease fence.`,
+          });
+        }
+      }
+
       // A same-column move is only a reorder: the QA dwell and server lease
       // remain open. Read the source immediately before the governed write so
       // this process drops its capability only when the move truly transitions
@@ -1356,6 +1462,12 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
           // about the assignee at all.
           claim: args.claim === true ? true : undefined,
           force: args.force === true ? true : undefined,
+          // The API's documented escape hatch, which this connector used to
+          // drop on the floor: the field was never in the body, so a person
+          // driving the board through MCP could be refused a QA exit and had
+          // no way to record the override the refusal told them to send.
+          acknowledgeUnmetCriteria:
+            args.acknowledgeUnmetCriteria === true ? true : undefined,
           receipt: args.receipt,
         },
         headers: mutationHeadersForItem(args, args.itemId),
@@ -1494,6 +1606,106 @@ This is both halves of the developer loop. Claiming is a parameter and not a sec
     }
   );
 
+  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}`,
@@ -1624,7 +1836,7 @@ Pass kind:null to clear it back to UNTYPED. Untyped is a real state and is NOT t
     'create_work_item',
     `Create a card on a board. Lands in the named column, or in Backlog on a standard board when none is given.
 
-ACCEPTANCE CRITERIA ARE FIRST-CLASS RECORDS, not prose buried in \`body\`. Use \`acceptanceCriteria\` for the executable definition of done: where to check, any starting state, what action to perform, and the observable result. The card and every criterion are replay-safe under one idempotency-key family, so a retry after a partial failure cannot duplicate either. If you cannot write criteria, capture what you know in \`body\`; the preview will mark the card as not ready rather than inventing outcomes nobody agreed to.
+ACCEPTANCE CRITERIA ARE FIRST-CLASS RECORDS, not prose buried in \`body\`. Use \`acceptanceCriteria\` for the executable definition of done: where to check, any starting state, what action to perform, and the observable result. Author the proof route at the same time: \`verificationRoute\` is REQUIRED on every criterion, because an omitted route silently became \`product\` and that is what a browser recording is then demanded for. Use \`engineering\`/\`both\` with a plain-language \`engineeringReason\` when no meaningful product-person retest exists. The card and every criterion are replay-safe under one idempotency-key family, so a retry after a partial failure cannot duplicate either. If you cannot write criteria, capture what you know in \`body\`; the preview will mark the card as not ready rather than inventing outcomes nobody agreed to.
 
 ONE CARD IS ONE QA JUDGEMENT. If your criteria list needs QA to make more than one call ("follows the OS theme" AND "the toggle persists" AND "every surface is restyled"), that is several cards, not one — a bounce from a multi-outcome card names nothing actionable. Implementation steps ("create a React hook", "rename the CSS variables") are never cards; they are lines inside one.
 
@@ -1645,6 +1857,24 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
             givenText: z.string().optional().describe('Starting state, when one is required.'),
             whenText: z.string().describe('Action the verifier performs.'),
             thenText: z.string().describe('Observable result that must follow.'),
+            verificationRoute: z
+              .enum(['product', 'engineering', 'both'])
+              .describe(
+                'REQUIRED. How this criterion gets proved. `product` needs a ' +
+                'signed-in browser recording; `engineering` needs executed code/' +
+                'test/runtime proof; `both` needs BOTH and is the STRICTEST of ' +
+                'the three, not a compromise. Choose from what the thenText ' +
+                'says: can a browser DISPLAY the result? Then product. Is the ' +
+                'result an ECS task definition, a migration receipt, a CI leg, ' +
+                'an HTTP status contract, a log record, a vendor invoice or a ' +
+                'test suite? Then engineering.'
+              ),
+            engineeringReason: z
+              .string()
+              .optional()
+              .describe(
+                'Required for engineering or both: why no meaningful product-person retest exists.'
+              ),
           })
         )
         .optional()
@@ -1737,19 +1967,40 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         );
         criteria.push(result?.data);
       }
-      return ok({ created: true, item, criteria });
+      return ok({
+        created: true,
+        item: await reconcileCriteriaCount(api, item, criteria),
+        criteria,
+      });
     }
   );
 
   server.tool(
     'add_work_item_acceptance_criterion',
-    `Add one executable acceptance criterion to a card. This is grooming, not a comment: write where the check runs, the action, and the observable result. The server keeps criteria ordered and auditable.${GOVERNED_NOTE}`,
+    `Add one executable acceptance criterion to a card. This is grooming, not a comment: write where the check runs, the action, the observable result, and its proof route. verificationRoute is REQUIRED -- an omitted route silently became product, which then demands a browser recording for a criterion about a CI job. engineering and both require a plain-language engineeringReason. The server stores the criterion and its initial route audit receipt atomically.${GOVERNED_NOTE}`,
     {
       itemId: z.string().describe('Card id.'),
       whereText: z.string().describe('Surface, environment, account, or role to check.'),
       givenText: z.string().optional().describe('Starting state, when one is required.'),
       whenText: z.string().describe('Action the verifier performs.'),
       thenText: z.string().describe('Observable result that must follow.'),
+      verificationRoute: z
+        .enum(['product', 'engineering', 'both'])
+        .describe(
+          'REQUIRED. How this criterion gets proved. `product` needs a signed-in ' +
+          'browser recording; `engineering` needs executed code/test/runtime ' +
+          'proof; `both` needs BOTH and is the STRICTEST of the three, not a ' +
+          'compromise. Choose from what the thenText says: can a browser ' +
+          'DISPLAY the result? Then product. Is the result an ECS task ' +
+          'definition, a migration receipt, a CI leg, an HTTP status contract, ' +
+          'a log record, a vendor invoice or a test suite? Then engineering.'
+        ),
+      engineeringReason: z
+        .string()
+        .optional()
+        .describe(
+          'Required for engineering or both: why no meaningful product-person retest exists.'
+        ),
       dryRun: z.boolean().optional().describe('Defaults to true. Set false to add it.'),
       approved: z.boolean().optional().describe('Required true for a live write.'),
       reason: z
@@ -1771,6 +2022,8 @@ YOU DO NOT NEED TO SAY WHO IS CREATING IT. The card records its creator from you
         givenText: args.givenText,
         whenText: args.whenText,
         thenText: args.thenText,
+        verificationRoute: args.verificationRoute,
+        engineeringReason: args.engineeringReason,
       };
       if (preview?.dryRun) return ok({ ...preview, wouldAdd: { itemId: args.itemId, criterion } });
       const data = await api('POST', path, {
@@ -1781,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.
@@ -2163,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',
 ];