@taiga-ai/mcp-server 0.19.0-rc.452 → 0.20.0-dev.454

package/src/tools/builds.ts

@@ -35,6 +35,8 @@ export const BUILD_SUMMARY_FIELDS = [
   'prState',
   'prDraft',
   'prMerged',
+  'reviewEscalation',
+  'error',
   'actions',
   'createdAt',
   'startedAt',
@@ -52,7 +54,10 @@ const RUN_OUTCOME_FIELDS = [
   'totalSteps',
   'prNumber',
   'prUrl',
+  'prDraft',
   'prMerged',
+  'reviewEscalation',
+  'error',
   'actions',
 ] as const;
 
@@ -111,6 +116,75 @@ const RUNNING: Partial<Record<BuildRunStatus, string>> = {
   reviewing: 'answering review comments on the pull request',
 };
 
+/** Why the agent handed a run back, in the web's words (apps/web handback), with the checks it names. */
+export function handbackSaid(escalation: unknown): string | null {
+  if (!escalation || typeof escalation !== 'object') return null;
+  const e = escalation as {
+    reason?: unknown;
+    rounds?: unknown;
+    failingChecks?: unknown;
+    file?: unknown;
+    blockers?: unknown;
+  };
+  const checks = Array.isArray(e.failingChecks)
+    ? (e.failingChecks as { name?: unknown }[]).map((check) => String(check.name)).join(', ')
+    : '';
+  const on = checks ? ` on ${checks}` : '';
+  const rounds =
+    typeof e.rounds === 'number' && e.rounds > 0
+      ? ` after ${e.rounds} automatic round${e.rounds === 1 ? '' : 's'}`
+      : '';
+  const blockers = Array.isArray(e.blockers)
+    ? (e.blockers as unknown[]).map((b) => READY_BLOCKER_SAID[String(b)] ?? String(b))
+    : [];
+  switch (e.reason) {
+    case 'ci_fix_cap':
+      return `CI is still failing${on}${rounds}`;
+    case 'ci_fix_stalled':
+      return `CI is still failing${on}, and the last fix round changed nothing`;
+    case 'conflict_cap':
+      return `the branch still conflicts with its base${rounds}`;
+    case 'review_bot_cap':
+      return `review bots still have open comments${rounds}`;
+    case 'ci_never_settled':
+      return 'CI did not finish in time';
+    case 'ready_blocked':
+      return `CI is green, but Taiga kept the pull request a draft${blockers.length ? `: ${blockers.join('; ')}` : ''}`;
+    case 'check_weakened':
+      return `CI went green only after a check was loosened${typeof e.file === 'string' ? ` in ${e.file}` : ''}`;
+    default:
+      return typeof e.reason === 'string' ? e.reason : null;
+  }
+}
+
+/** What a person does about a handback, by its reason, as the web's handback detail says it. */
+export function handbackNextStep(escalation: unknown): string {
+  const reason = escalation && typeof escalation === 'object' ? (escalation as { reason?: unknown }).reason : null;
+  if (reason === 'check_weakened') return 'review the loosened check before merging, or review it back to the agent';
+  if (reason === 'ci_never_settled')
+    return 'look at what is still running or queued in CI, then review it back to the agent';
+  return 'fix it by hand or review it back to the agent';
+}
+
+/** The web's words for why Taiga keeps a pull request a draft. */
+const READY_BLOCKER_SAID: Record<string, string> = {
+  plan_incomplete: 'not every planned step shipped',
+  tests_failed: 'the tests Taiga ran after the build failed',
+  bar_lowering: 'a fix lowered a check instead of fixing the code',
+  bar_lowering_unchecked: 'Taiga could not check whether a fix lowered a check',
+  criticals_unresolved: "Taiga's own review left a critical issue unresolved",
+};
+
+/** The first sentence of a run's error, short enough for a row. */
+function errorSaid(error: unknown): string | null {
+  if (typeof error !== 'string' || !error.trim()) return null;
+  const first = error
+    .trim()
+    .split(/\n|(?<=[.!?])\s/)[0]!
+    .replace(/[.!?]$/, '');
+  return first.length > 240 ? `${first.slice(0, 240).trimEnd()}...` : first;
+}
+
 /**
  * How a run stands, in one sentence, with its disposition: the meaning the
  * status and the pull request facts carry between them
@@ -127,18 +201,24 @@ export function runOutcome(run: Record<string, unknown>): { disposition: string;
     typeof run['completedSteps'] === 'number' && typeof run['totalSteps'] === 'number'
       ? ` (${run['completedSteps']} of ${run['totalSteps']} steps done)`
       : '';
-  const reason = typeof run['failedReason'] === 'string' && run['failedReason'] ? `: ${run['failedReason']}` : '';
+  // The error says what happened; the failedReason is only its code (PRO-2800).
+  const why = errorSaid(run['error']) ?? (typeof run['failedReason'] === 'string' ? run['failedReason'] : null);
+  const handback = handbackSaid(run['reviewEscalation']);
+  const draft = run['prDraft'] === true ? `, still a draft` : '';
   const sentence: Record<string, string> = {
     in_flight: status === 'pending' ? 'Queued: waiting to start.' : `Running: ${RUNNING[status] ?? status}${progress}.`,
-    gated: `Waiting for a person to review and merge ${pr}.`,
+    // A handback is a person's turn too, but not a plain review: say what the agent could not get past.
+    gated: handback
+      ? `Handed back to a person: ${handback}. ${pr}${draft ? `${draft},` : ''} waits for them to ${handbackNextStep(run['reviewEscalation'])}.`
+      : `Waiting for a person to review and merge ${pr}${draft}.`,
     succeeded: `Merged: ${pr} is in ${typeof run['baseBranch'] === 'string' ? run['baseBranch'] : 'the base branch'}.`,
     unmerged:
       typeof run['prNumber'] === 'number' || run['prUrl']
         ? `Settled without merging: ${pr} was left unmerged.`
         : 'Settled without a merged pull request.',
-    failed: `Failed${reason}${progress}.`,
+    failed: `Failed${why ? `: ${why}` : ''}${progress}.`,
     stopped: `Stopped before it finished${progress}.`,
-    rejected: `${pr} was closed without merging, so the work did not land.`,
+    rejected: `${pr} was closed without merging, so the work did not land.${handback ? ` It had been handed back: ${handback}.` : ''}`,
   };
   return { disposition, outcome: sentence[disposition] ?? status };
 }
@@ -146,19 +226,26 @@ export function runOutcome(run: Record<string, unknown>): { disposition: string;
 /**
  * A run row as an agent reads it: its outcome added, and prDraft only where
  * there is a pull request. The column defaults to true, so a run that never
- * opened one said it had a draft (PRO-2800).
+ * opened one said it had a draft (PRO-2800). A list row leaves the full error
+ * text out: its first sentence is in the outcome, and taiga_get_run has it all.
  */
-export function readableRun(run: Record<string, unknown>): Record<string, unknown> {
-  const { prDraft, ...rest } = run;
+export function readableRun(run: Record<string, unknown>, opts: { row?: boolean } = {}): Record<string, unknown> {
+  const { prDraft, error, reviewEscalation, ...rest } = run;
   const said = runOutcome(run);
   return {
     ...rest,
+    // A row's outcome says the error and the handback; the full read keeps them whole.
+    ...(opts.row || error === undefined ? {} : { error }),
+    ...(opts.row || reviewEscalation === undefined ? {} : { reviewEscalation }),
     // A PR number proves a PR exists (isSettledWithoutPr); the URL is nullable apart from it.
     ...(typeof rest['prNumber'] === 'number' || rest['prUrl'] ? { prDraft } : {}),
     ...(said ?? {}),
   };
 }
 
+/** readableRun for a list row. */
+export const readableRow = (run: Record<string, unknown>) => readableRun(run, { row: true });
+
 /** How many products the org-wide list names; past this a row keeps its productId only. */
 const NAMED_PRODUCTS = 100;
 
@@ -218,7 +305,7 @@ async function activityRows(
     nameById.set(product.id, { name: product.name, slug: product.slug });
   }
   const rows = pickFields(runs.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS)
-    .map(readableRun)
+    .map(readableRow)
     .map((row) => {
       const product = nameById.get(String(row['productId']));
       return product ? { ...row, product } : row;
@@ -293,7 +380,7 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
           });
           return toolResult(
             page(
-              pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS).map(readableRun),
+              pickFields(result.data as Record<string, unknown>[], BUILD_SUMMARY_FIELDS).map(readableRow),
               result.nextCursor
             )
           );
@@ -307,7 +394,7 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Get run',
       description:
-        'Get one run with its steps: how it stands (outcome, disposition), its pull request and hardening, and ' +
+        'Read one run with its steps: how it stands (outcome, disposition), its pull request and hardening, and ' +
         "each step's title, status, commit, files changed, verification and headline, the first paragraph of " +
         "what the agent reported. A step's verification is Taiga's own check after the step (tests, lint, build), " +
         'independent of what the agent says it ran: a docs-only step can show tests failed because the ' +
@@ -367,7 +454,7 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         const result = await client.stopBuildRun(params.runId);
-        return toolResult(readableRun(pickFields([result.data as Record<string, unknown>], RUN_OUTCOME_FIELDS)[0]!));
+        return toolResult(readableRow(pickFields([result.data as Record<string, unknown>], RUN_OUTCOME_FIELDS)[0]!));
       })
   );
 }

package/src/tools/catalogue.test.ts

@@ -167,6 +167,6 @@ describe('writeNotice', () => {
   it('says nothing for a read, and what a write does otherwise', () => {
     expect(writeNotice('r', { readOnlyHint: true })).toBe('');
     expect(writeNotice('w', { readOnlyHint: false })).toBe('Writes. ');
-    expect(writeNotice('o', { readOnlyHint: false, destructiveHint: true })).toMatch(/^Acts on paid or shared work/);
+    expect(writeNotice('o', { readOnlyHint: false, destructiveHint: true })).toMatch(/^Ask first: paid or shared work/);
   });
 });

package/src/tools/context.ts

@@ -28,7 +28,7 @@ import {
   type StoredDocument,
 } from './sections.js';
 import { pickFields } from './summarize.js';
-import { readableRun } from './builds.js';
+import { readableRow } from './builds.js';
 import { setupReadiness } from './readiness.js';
 import { standingSummary } from './maintenance.js';
 
@@ -72,6 +72,9 @@ const CONTEXT_BUILD_FIELDS = [
   'prUrl',
   'prState',
   'prMerged',
+  'prDraft',
+  'reviewEscalation',
+  'error',
   'createdAt',
 ] as const;
 
@@ -127,12 +130,12 @@ const PARTS = {
   factory: 'factories:read',
   documents: 'products:read',
   policies: 'tenant:documents:read',
-  backlog: 'backlog:read',
+  initiatives: 'backlog:read',
   repositories: 'products:read',
-  builds: 'products:read',
-  attention: 'products:read',
+  runs: 'products:read',
+  actionRequired: 'products:read',
   maintenance: 'products:read',
-  standing: 'products:read',
+  policyStanding: 'products:read',
 } as const;
 type Part = keyof typeof PARTS;
 
@@ -316,8 +319,8 @@ async function backlogPart(client: TaigaClient, productId: string) {
  * The linked repositories. The route serves one page of 100 and takes no
  * cursor, so past that the bundle says the list is cut rather than complete.
  */
-async function repositoriesPart(client: TaigaClient, productId: string) {
-  const result = await client.listProductRepositories(productId);
+async function repositoriesPart(links: () => ReturnType<TaigaClient['listProductRepositories']>) {
+  const result = await links();
   return {
     items: pickFields(result.data, REPOSITORY_SUMMARY_FIELDS),
     truncated: result.nextCursor !== null,
@@ -326,7 +329,7 @@ async function repositoriesPart(client: TaigaClient, productId: string) {
 
 async function buildsPart(client: TaigaClient, productId: string) {
   const rows = (await client.listBuildRuns(productId, { limit: BUILDS_IN_CONTEXT })).data as Record<string, unknown>[];
-  return pickFields(rows, CONTEXT_BUILD_FIELDS).map(readableRun);
+  return pickFields(rows, CONTEXT_BUILD_FIELDS).map(readableRow);
 }
 
 /**
@@ -370,8 +373,20 @@ async function maintenancePart(client: TaigaClient, productId: string) {
 
 /** Where the product stands against the policies, as counts; taiga_get_policy_standing has each violation. */
 async function standingPart(client: TaigaClient, productId: string) {
-  const summary = standingSummary((await client.getPolicyStanding(productId)).data);
-  return { openViolations: summary.violations, bySeverity: summary.bySeverity, controlsViolated: summary.controls };
+  const standing = (await client.getPolicyStanding(productId)).data;
+  const summary = standingSummary(standing);
+  // No violations from an assessment that never ran, or failed, is no all-clear (PRO-2800).
+  const state = (standing.assessment as { state?: unknown } | null | undefined)?.state;
+  return {
+    openViolations: summary.violations,
+    bySeverity: summary.bySeverity,
+    controlsViolated: summary.controls,
+    ...(state === 'never' || state === 'failed'
+      ? {
+          note: `The assessment ${state === 'never' ? 'has never run' : 'failed'}: no violations here is not an all-clear.`,
+        }
+      : {}),
+  };
 }
 
 export async function productContext(
@@ -383,21 +398,24 @@ export async function productContext(
   const granted = (part: Part) => client.hasCapability(PARTS[part]);
   const notGranted = (Object.keys(PARTS) as Part[]).filter((part) => !granted(part));
 
+  // One read of the links serves the repositories part and the setup readiness.
+  let linksRead: ReturnType<TaigaClient['listProductRepositories']> | undefined;
+  const links = () => (linksRead ??= client.listProductRepositories(productId));
   const fetchers: Record<Part, () => Promise<unknown>> = {
     factory: () => factoryPart(client, String(product.factoryId)),
     documents: () => documentsPart(client, product, options.documents),
     policies: () => policiesPart(client),
-    backlog: () => backlogPart(client, productId),
-    repositories: () => repositoriesPart(client, productId),
-    builds: () => buildsPart(client, productId),
-    attention: () => attentionPart(client, productId),
+    initiatives: () => backlogPart(client, productId),
+    repositories: () => repositoriesPart(links),
+    runs: () => buildsPart(client, productId),
+    actionRequired: () => attentionPart(client, productId),
     maintenance: () => maintenancePart(client, productId),
-    standing: () => standingPart(client, productId),
+    policyStanding: () => standingPart(client, productId),
   };
   const parts = (Object.keys(fetchers) as Part[]).filter(granted);
   const [settled, readiness] = await Promise.all([
     Promise.allSettled(parts.map((part) => fetchers[part]())),
-    setupReadiness(client, product),
+    setupReadiness(client, product, links),
   ]);
 
   const bundle: Record<string, unknown> = {
@@ -445,18 +463,17 @@ export function registerContextTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Get product context',
       description:
-        'Where a product stands and everything a coding session starts from, in one call. Name the product by ' +
-        'ID, slug or the git remote URL of a checkout. It carries: the product (and, while in setup, readiness: ' +
-        'what it still needs and the next move); its factory with the instructions in full; the specification ' +
-        'and architecture as outlines (section ids and sizes); every published policy as its section ids; the ' +
-        'open initiatives (not the done or canceled ones: taiga_list_initiatives has those); the linked ' +
-        'repositories; the latest runs, each with its outcome in a sentence; attention, what waits on a person ' +
-        'for it, counted by kind; maintenance, open findings by severity and the last sweep; standing, open ' +
-        'policy violations by severity. A part the API refused or failed is named under unavailable; a part the ' +
-        'key cannot read under notGranted; neither is shown as empty. Before writing code, documents: budget ' +
-        `brings the whole sections that fit, about ${DOCUMENT_BUDGET / 1000}k characters each, and full brings ` +
-        'them whole (tens of thousands of tokens on a large product). Unlike taiga_get_product, which is the ' +
-        'product record and its settings alone. Call this first, then read what you need.',
+        'Where a product stands, in one call: the first read for any question about a product. Name it by ID, ' +
+        'slug or the git remote URL of a checkout. The parts: product (and, while in setup, readiness: what it ' +
+        'still needs and the next move); factory, with its instructions in full; documents, the specification and ' +
+        'architecture as outlines (section ids and sizes); policies, each published policy with its section ids; ' +
+        'initiatives, the open ones (taiga_list_initiatives has the done and canceled); repositories; runs, the ' +
+        'latest ten, each with its outcome in a sentence; actionRequired, what waits on a person, counted by kind; ' +
+        'maintenance, open findings by severity and the last sweep; policyStanding, open policy violations by ' +
+        'severity. A part the API refused or failed is named under unavailable, a part the key cannot read under ' +
+        'notGranted; neither is shown as empty. Before writing code, documents: budget brings the whole sections ' +
+        `that fit, about ${DOCUMENT_BUDGET / 1000}k characters each, and full brings them whole. taiga_get_product ` +
+        'is the product record and its settings alone.',
       inputSchema: z.object({
         productId: productId.optional(),
         slug: slug.optional(),

package/src/tools/errors.ts

@@ -8,7 +8,11 @@ import { withNotFoundHint } from './hints.js';
  * as taiga_get_initiative and taiga_get_run ask for them, rather than the
  * storage names backlogItemId and buildRunId.
  */
-const PRODUCT_WORDS: Record<string, string> = { backlogItemId: 'initiativeId', buildRunId: 'runId' };
+const PRODUCT_WORDS: Record<string, string> = {
+  backlogItemId: 'initiativeId',
+  buildRunId: 'runId',
+  latestBuild: 'latestRun',
+};
 
 /**
  * Maps whose keys are content, not API fields: a document's sections are keyed
@@ -34,6 +38,14 @@ export function inProductWords(value: unknown): unknown {
   return out;
 }
 
+/** The API's 404 sentence in the product's words: "Backlog item not found" is an initiative not found. */
+export function inProductWording(said: string): string {
+  return said
+    .replace(/^Backlog item not found/i, 'Initiative not found')
+    .replace(/^Build run step not found/i, 'Run step not found')
+    .replace(/^Build run not found/i, 'Run not found');
+}
+
 /** A successful tool result: one JSON text block the model reads. */
 export function toolResult(value: unknown): CallToolResult {
   return { content: [{ type: 'text', text: JSON.stringify(inProductWords(value), null, 2) }] };
@@ -116,7 +128,7 @@ export async function runTool(handler: () => Promise<CallToolResult>): Promise<C
       const code = error.code ?? CODE_BY_STATUS[error.status] ?? 'API_ERROR';
       const said = error.apiMessage ?? `Taiga API answered ${error.status}.`;
       // A miss says where the right IDs are (hints.ts): the API's own word is bare.
-      const message = error.status === 404 ? withNotFoundHint(said) : said;
+      const message = error.status === 404 ? withNotFoundHint(inProductWording(said)) : said;
       return toolError(code, message, error.details);
     }
     if (isNetworkFailure(error)) {

package/src/tools/inbox.ts

@@ -64,21 +64,75 @@ function itemRow(row: Row, now: number, full: boolean): Row {
 }
 
 /** What is open, counted by product and kind: the answer to "what needs attention" without reading every row. */
-function summaryOf(rows: Row[]): Row[] {
+function summaryOf(rows: Row[], stale: Map<string, string>): Row[] {
   const byProduct = new Map<
     string,
-    { productId: string; product: unknown; open: number; byKind: Record<string, number> }
+    { productId: string; product?: unknown; open: number; byKind: Record<string, number>; stale?: number }
   >();
   for (const row of rows) {
     const key = String(row['productId']);
-    const entry = byProduct.get(key) ?? { productId: key, product: row['productName'] ?? key, open: 0, byKind: {} };
+    // A product-scoped read carries no names; the id is the product's, not a name.
+    const entry =
+      byProduct.get(key) ??
+      (row['productName']
+        ? { productId: key, product: row['productName'], open: 0, byKind: {} }
+        : { productId: key, open: 0, byKind: {} });
     entry.open += 1;
     entry.byKind[String(row['kind'])] = (entry.byKind[String(row['kind'])] ?? 0) + 1;
+    if (stale.has(String(row['id']))) entry.stale = (entry.stale ?? 0) + 1;
     byProduct.set(key, entry);
   }
   return [...byProduct.values()].sort((a, b) => b.open - a.open);
 }
 
+/** Pull request reviews checked against their run and initiative; past this a row is left as it is. */
+const STALE_CHECKS = 10;
+
+/**
+ * Which "Review & merge" items no longer stand, and why (PRO-2800): the run's
+ * pull request closed or merged, or its initiative was canceled or finished
+ * without it. Two reviewing agents counted such leftovers as live gates; the
+ * row still is open in Action Required, so this says what it is now rather
+ * than hiding it. Best effort, a handful of runs: a failed read leaves the
+ * row as it was.
+ */
+async function staleReviews(
+  client: TaigaClient,
+  rows: Row[]
+): Promise<{ stale: Map<string, string>; unchecked: number }> {
+  const byId = new Map(
+    rows
+      .filter((row) => row['kind'] === 'review_pr' && row['subjectType'] === 'build_run')
+      .map((row) => [String(row['id']), row])
+  );
+  const candidates = [...byId.values()].slice(0, STALE_CHECKS);
+  // Past the cap, and any check the API refused or failed (a key without
+  // backlog:read cannot read the initiative): unknown, not live.
+  let unchecked = byId.size - candidates.length;
+  const out = new Map<string, string>();
+  await Promise.all(
+    candidates.map(async (row) => {
+      try {
+        const run = (await client.getBuildRun(String(row['subjectId']))).data as unknown as Row;
+        if (run['prMerged'] === true) return void out.set(String(row['id']), 'its pull request has merged');
+        if (run['prState'] === 'closed') return void out.set(String(row['id']), 'its pull request was closed');
+        if (typeof run['backlogItemId'] !== 'string') return;
+        if (!client.hasCapability('backlog:read')) return void (unchecked += 1);
+        const item = (await client.getBacklogItem(run['backlogItemId'])).data as unknown as Row;
+        if (item['state'] === 'canceled' || item['status'] === 'canceled') {
+          out.set(String(row['id']), 'its initiative was canceled; the pull request is still open on the forge');
+        } else if (item['state'] === 'done' || item['status'] === 'done') {
+          out.set(String(row['id']), 'its initiative is done; this run is not the one that landed it');
+        }
+      } catch (error) {
+        if (!(error instanceof TaigaApiError || isNetworkFailure(error))) throw error;
+        unchecked += 1;
+      }
+    })
+  );
+  return { stale: out, unchecked };
+}
+
 /** Pages read for the summary; past this it says it counted only those. */
 const SUMMARY_PAGE = 100;
 
@@ -146,6 +200,11 @@ export function sameKeyOnce(rows: Row[]): Row[] {
   return out;
 }
 
+/** A page of folded rows, saying how many records it folded so totalCount (records) and the rows reconcile. */
+function folded(rows: Row[], nextCursor: string | null, records: number) {
+  return { ...page(rows, nextCursor), ...(rows.length < records ? { recordsOnPage: records } : {}) };
+}
+
 export function registerInboxTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:read')) return;
 
@@ -154,13 +213,16 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
     {
       title: 'List what needs a person',
       description:
-        'Read Action Required, where work comes back to a person, shared by the team: things to review (a plan, ' +
+        "What waits on a person: reviews and setup items, with a summary by product. The inbox is the team's, not one " +
+        "person's. It holds things to review (a plan, " +
         'a set of initiatives, a document decision, a pull request, maintenance findings, new policy violations) ' +
         'and things to set up that only a person can (a secret, an environment variable, an account, a package ' +
         'registry, a cloud permission). Across every product the key can open, or one product. The first page ' +
         'opens with summary: what is open, counted by product and kind, so "what needs attention" is one call, ' +
         'and totalCount. Each row says how many days it has waited (waitingDays) and, for a pull request review, ' +
-        'the prUrl; an old item is still open, not stale. category gate is the reviews, setup the setup items; ' +
+        'the prUrl. A pull request review that no longer stands (its pull request merged or closed, or its ' +
+        'initiative canceled or done) says so under stale, and the summary counts those per product. ' +
+        'category gate is the reviews, setup the setup items; ' +
         'resolved: true reads the archive. An item snoozed until later is left out until then (snoozedHidden ' +
         "counts them). full: true adds each item's metadata. Unlike taiga_list_setup_tasks, which lists the setup " +
         'items with exactly what to set and where.',
@@ -210,19 +272,34 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         const rows = result.data as Row[];
         const due = rows.filter(isDue);
         const hidden = rows.length - due.length;
+        const overviewDue = overview ? (overview.data as Row[]).filter(isDue) : [];
+        const checked = resolved
+          ? { stale: new Map<string, string>(), unchecked: 0 }
+          : await staleReviews(client, [...due, ...overviewDue]);
+        const stale = checked.stale;
         return toolResult({
           ...(overview
             ? {
-                summary: summaryOf((overview.data as Row[]).filter(isDue)),
+                summary: summaryOf(overviewDue, stale),
                 ...(overview.nextCursor ? { summaryNote: `The summary counts the first ${SUMMARY_PAGE} items.` } : {}),
               }
             : {}),
           ...page(
-            due.map((row) => itemRow(row, now, full === true)),
+            due.map((row) => {
+              const item = itemRow(row, now, full === true);
+              const why = stale.get(String(row['id']));
+              return why ? { ...item, stale: why } : item;
+            }),
             result.nextCursor
           ),
           ...totalOf(result),
           ...(hidden > 0 ? { snoozedHidden: hidden } : {}),
+          // Past the cap a review is not checked, so no stale on it is not "live".
+          ...(checked.unchecked > 0
+            ? {
+                staleNote: `${checked.unchecked} pull request review${checked.unchecked === 1 ? ' was' : 's were'} not checked for staleness (past the cap, or the read was refused).`,
+              }
+            : {}),
         });
       })
   );
@@ -232,7 +309,7 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
     {
       title: 'List setup tasks',
       description:
-        'The setup tasks agents raised for work only a person can do, with what exactly to set and where: the ' +
+        'What a person must set up for a product (secrets, variables, accounts), with exactly what and where. These are the tasks agents raised for work only a person can do: the ' +
         'name of an environment variable, secret or API key to create (key; never its value, which Taiga does ' +
         'not store or display), the provider page to do it on, and the phase that says when it blocks you ' +
         '(prereq: before the deploy, which fails without it; wiring: connecting generated values back to ' +
@@ -241,8 +318,8 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         'product), or one. The tasks still to do, oldest first, the order they depend on each other; ' +
         'includeDone: true adds the done and dismissed ones. The first page says how many there are on every ' +
         'page (totalCount). One row per variable: a variable filed twice (as a secret and as an environment ' +
-        'variable) lists the other records under alsoFiledAs, an open one first; within a page, and totalCount ' +
-        'counts every record. Unlike taiga_list_action_required, whose setup ' +
+        'variable) lists the other records under alsoFiledAs, an open one first (folded within a page). totalCount counts ' +
+        'records, and a page that folded some says recordsOnPage. Unlike taiga_list_action_required, whose setup ' +
         'items are the same work as rows to resolve, this says exactly what to set and where.',
       inputSchema: z.object({
         productId: productId.optional(),
@@ -260,7 +337,11 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
           ...(params.cursor === undefined ? { withTotal: true } : {}),
         });
         return toolResult({
-          ...page(sameKeyOnce(pickFields(result.data as Row[], SETUP_TASK_FIELDS)), result.nextCursor),
+          ...folded(
+            sameKeyOnce(pickFields(result.data as Row[], SETUP_TASK_FIELDS)),
+            result.nextCursor,
+            result.data.length
+          ),
           ...totalOf(result),
         });
       })