@taiga-ai/mcp-server 0.18.0-rc.445 → 0.19.0-dev.451

package/src/tools/sections.ts

@@ -15,15 +15,42 @@ import type { CallToolResult } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { toolError, toolResult } from './errors.js';
 
-/** A section as stored: an object with `content` and metadata, or (older rows) a bare string. */
+/** A document's section map, keyed by section id: each value a `StoredSection` or (older rows) a bare string. */
 export type Sections = Record<string, unknown>;
 
+/** A section stored as an object: its text and the metadata an edit keeps. */
+export interface StoredSection {
+  content?: unknown;
+  title?: unknown;
+  priority?: unknown;
+  [key: string]: unknown;
+}
+
+/** A document's `data`: a section-shaped document keeps its content under `sections`. */
+export interface DocumentData {
+  sections?: unknown;
+  [key: string]: unknown;
+}
+
+/** A document as these helpers read it: its `data` and the provenance a reader does not need. */
+export interface StoredDocument {
+  data?: unknown;
+  derivedFrom?: unknown;
+  outdated?: unknown;
+  [key: string]: unknown;
+}
+
 export function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/** A section stored as an object rather than a bare string. */
+export function isSectionObject(value: unknown): value is StoredSection {
+  return isRecord(value);
+}
+
 /** The `sections` map of a document, or null when the document is not section-shaped. */
-export function sectionsOf(data: Record<string, unknown>): Sections | null {
+export function sectionsOf(data: DocumentData): Sections | null {
   return isRecord(data.sections) ? data.sections : null;
 }
 
@@ -32,7 +59,7 @@ export function sectionContent(sections: Sections, sectionId: string): string |
   const section = sections[sectionId];
   if (section === undefined || section === null) return null;
   if (typeof section === 'string') return section;
-  return isRecord(section) && typeof section.content === 'string' ? section.content : '';
+  return isSectionObject(section) && typeof section.content === 'string' ? section.content : '';
 }
 
 /** The map with one section's text replaced (or the section added); every other section untouched. */
@@ -48,10 +75,12 @@ export function applySectionEdit(sections: Sections, sectionId: string, content:
  * the editor needs and a reader does not; `source` and `priority` stay, the
  * server instructions explain them.
  */
-export function stripProvenance(doc: Record<string, unknown>): Record<string, unknown> {
+export function stripProvenance<T extends StoredDocument>(doc: T): Omit<T, 'derivedFrom' | 'outdated'> {
   const { derivedFrom: _derivedFrom, outdated: _outdated, ...rest } = doc;
-  if (!isRecord(rest.data)) return rest;
-  const sections = sectionsOf(rest.data);
+  // `rest` holds the same `data`; read through `doc`, whose type still names it.
+  const { data } = doc;
+  if (!isRecord(data)) return rest;
+  const sections = sectionsOf(data);
   if (!sections) return rest;
   const stripped = Object.fromEntries(
     Object.entries(sections).map(([id, section]) => {
@@ -60,7 +89,7 @@ export function stripProvenance(doc: Record<string, unknown>): Record<string, un
       return [id, keep];
     })
   );
-  return { ...rest, data: { ...rest.data, sections: stripped } };
+  return { ...rest, data: { ...data, sections: stripped } };
 }
 
 /**
@@ -73,7 +102,7 @@ export function instructionsText(sections: Sections): string | null {
   for (const section of Object.values(sections)) {
     // Object sections only, as the API's extractor reads them: a bare-string
     // row the agents never receive is not handed to the model here either.
-    const content = isRecord(section) ? section.content : undefined;
+    const content = isSectionObject(section) ? section.content : undefined;
     if (typeof content === 'string' && content.trim()) parts.push(content.trim());
   }
   const text = parts.join('\n\n').trim();
@@ -82,15 +111,15 @@ export function instructionsText(sections: Sections): string | null {
 
 /** A document cut to some of its sections, and the ones left out with their sizes. */
 export interface SectionCut {
-  doc: Record<string, unknown>;
+  doc: StoredDocument;
   omittedSections: { id: string; characters: number }[];
 }
 
-function cutTo(doc: Record<string, unknown>, sections: Sections, kept: Sections): SectionCut {
+function cutTo(doc: StoredDocument, sections: Sections, kept: Sections): SectionCut {
   const omittedSections = Object.keys(sections)
     .filter((id) => !Object.hasOwn(kept, id))
     .map((id) => ({ id, characters: sectionContent(sections, id)?.length ?? 0 }));
-  return { doc: { ...doc, data: { ...(doc.data as Record<string, unknown>), sections: kept } }, omittedSections };
+  return { doc: { ...doc, data: { ...(doc.data as DocumentData), sections: kept } }, omittedSections };
 }
 
 /**
@@ -100,7 +129,7 @@ function cutTo(doc: Record<string, unknown>, sections: Sections, kept: Sections)
  * every other section is listed with its size so the reader knows what else
  * there is. Null when the document is not made of sections.
  */
-export function pickSections(doc: Record<string, unknown>, ids: ReadonlySet<string>): SectionCut | null {
+export function pickSections(doc: StoredDocument, ids: ReadonlySet<string>): SectionCut | null {
   const sections = isRecord(doc.data) ? sectionsOf(doc.data) : null;
   if (!sections) return null;
   return cutTo(doc, sections, Object.fromEntries(Object.entries(sections).filter(([id]) => ids.has(id))));
@@ -115,7 +144,7 @@ export function pickSections(doc: Record<string, unknown>, ids: ReadonlySet<stri
  * and a later, smaller one may still be carried. Null when the document is
  * not made of sections.
  */
-export function budgetSections(doc: Record<string, unknown>, budget: number): SectionCut | null {
+export function budgetSections(doc: StoredDocument, budget: number): SectionCut | null {
   const sections = isRecord(doc.data) ? sectionsOf(doc.data) : null;
   if (!sections) return null;
   // Entries, not assignment: a section id is text, and `kept["__proto__"] = x` would set a prototype.
@@ -139,7 +168,7 @@ export const sectionsInput = z
   .max(50)
   .optional()
   .describe(
-    'Only these sections, by id; [] for the outline (every section id and its size, no text); omit for the whole document'
+    'Only these sections, by id; [] for the outline (under outline: every section id and its size, no text); omit for the whole document'
   );
 
 /**
@@ -150,11 +179,23 @@ export const sectionsInput = z
  * real id with its size, so the retry needs nothing else. No ids is the
  * outline.
  */
-export function sectionReadResult(doc: Record<string, unknown>, ids: readonly string[], label: string): CallToolResult {
+export function sectionReadResult(doc: StoredDocument, ids: readonly string[], label: string): CallToolResult {
   const cut = pickSections(doc, new Set(ids));
   if (!cut) return toolError('VALIDATION_ERROR', `The ${label} is not made of sections; read it without sections.`);
-  const all = Object.keys(sectionsOf(doc.data as Record<string, unknown>) ?? {});
+  const all = Object.keys(sectionsOf(doc.data as DocumentData) ?? {});
   const unknownSections = ids.filter((id) => !all.includes(id));
+  const known = ids.filter((id) => all.includes(id));
+  if (known.length === 0) {
+    // The outline, or a read naming only ids the document lacks: no text to
+    // carry, so no empty data.sections beside the ids, which read as a
+    // document with no sections (PRO-2800).
+    const { data: _data, ...meta } = cut.doc;
+    return toolResult({
+      ...meta,
+      outline: cut.omittedSections,
+      ...(unknownSections.length > 0 ? { unknownSections } : {}),
+    });
+  }
   return toolResult({
     ...cut.doc,
     omittedSections: cut.omittedSections,

package/src/tools/setup.ts

@@ -1,10 +1,12 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { DEPLOYMENT_NOTES_MAX_LENGTH, REALITY_DERIVED_DOCUMENT_TYPES } from '@taiga/types';
 import { z } from 'zod';
-import { TaigaApiError, type TaigaClient } from '../client.js';
+import type { Product } from '@taiga/types';
+import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
 import { OPERATE, OPERATE_SETTING, READ_ONLY, WRITE } from './annotations.js';
-import { isImportedProduct, setupNextStep, type ProductSettingsView } from './catalogue.js';
-import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
+import { isImportedProduct } from './catalogue.js';
+import { runTool, toolError, toolResult } from './errors.js';
+import { setupReadiness } from './readiness.js';
 import { withStop } from './hints.js';
 import { idInput, productId } from './inputs.js';
 import { pickFields } from './summarize.js';
@@ -18,8 +20,6 @@ import { pickFields } from './summarize.js';
  * a product stay in the web.
  */
 
-type Row = Record<string, unknown>;
-
 const PRODUCT_FIELDS = [
   'id',
   'name',
@@ -63,42 +63,25 @@ const MISSING_DOCUMENTS_HOW =
   'specification from the Discovery conversation in the web and the rest from taiga_generate_product_documents. ' +
   'A draft is published with taiga_publish_product_document.';
 
-/** A product row the model can act on, saying how it started as the other product tools say it. */
-async function productRow(client: TaigaClient, product: Row): Promise<Row> {
+type ProductRow = WithoutTenant<Product>;
+
+/** A product row the model can act on: how it started, and while in setup what it still needs. */
+async function productRow(client: TaigaClient, product: ProductRow) {
   const { settings: _settings, ...rest } = pickFields([product], PRODUCT_FIELDS)[0]!;
-  const nextStep = setupNextStep(await withDiscoveryStep(client, product));
+  const readiness = await setupReadiness(client, product);
   return {
     ...rest,
-    projectType: isImportedProduct(product as ProductSettingsView) ? 'brownfield' : 'greenfield',
-    ...(nextStep ? { nextStep } : {}),
+    projectType: isImportedProduct(product) ? 'brownfield' : 'greenfield',
+    ...(readiness ? { readiness } : {}),
   };
 }
 
-/**
- * The product with its discoveryStep. The API derives it on reads only, not
- * on the answer to a write (products.ts), and a draft started from scratch
- * needs it to say what comes next; an imported one reads its import status
- * instead. Best effort: a failed read leaves the product without a nextStep
- * rather than failing the write that already happened.
- */
-async function withDiscoveryStep(client: TaigaClient, product: Row): Promise<Row> {
-  if (product.status !== 'draft' || 'discoveryStep' in product || isImportedProduct(product as ProductSettingsView)) {
-    return product;
-  }
-  try {
-    return (await client.getProduct(String(product.id))).data as Row;
-  } catch (error) {
-    if (error instanceof TaigaApiError || isNetworkFailure(error)) return product;
-    throw error;
-  }
-}
-
 /**
  * A half turned off with nothing said about how it is done today. Allowed (the
  * web asks for the sentence but does not insist), so a warning rather than a
  * refusal: plans then design against a gap.
  */
-function missingNotesWarning(product: Row): string[] {
+function missingNotesWarning(product: ProductRow): string[] {
   const off = product.ownsInfrastructure === false || product.ownsDeployment === false;
   const notes = typeof product.deploymentNotes === 'string' ? product.deploymentNotes.trim() : '';
   return off && !notes
@@ -144,7 +127,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       },
       (params) =>
         runTool(async () =>
-          toolResult(pickFields([(await client.createFactory({ name: params.name })).data as Row], FACTORY_FIELDS)[0])
+          toolResult(pickFields([(await client.createFactory({ name: params.name })).data], FACTORY_FIELDS)[0])
         )
     );
 
@@ -161,10 +144,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       (params) =>
         runTool(async () =>
           toolResult(
-            pickFields(
-              [(await client.updateFactory(params.factoryId, { name: params.name })).data as Row],
-              FACTORY_FIELDS
-            )[0]
+            pickFields([(await client.updateFactory(params.factoryId, { name: params.name })).data], FACTORY_FIELDS)[0]
           )
         )
     );
@@ -193,8 +173,8 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
           'Move a product to another factory. Access follows the factory, so this changes who can reach the ' +
           "product (taiga_preview_product_move says who); the product's own knowledge files are re-filed onto " +
           'the new factory, and factory knowledge and instructions stay with the factory that owns them. Refused ' +
-          '(CONFLICT) while a plan or build is in flight: stopLine: true stops the line first and then moves, which ' +
-          'interrupts that work.',
+          '(WORK_IN_FLIGHT) while a plan or build is in flight. Then ask the person: stopLine: true stops the ' +
+          'line first and then moves, which interrupts that work.',
         inputSchema: z.object({
           productId,
           factoryId: factoryId.describe('The factory to move it to'),
@@ -207,12 +187,30 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       },
       (params) =>
         runTool(async () => {
-          const moved = await client.moveProduct(params.productId, {
-            factoryId: params.factoryId,
-            ...(params.stopLine ? { stopLine: true } : {}),
-          });
+          let moved;
+          try {
+            moved = await client.moveProduct(params.productId, {
+              factoryId: params.factoryId,
+              ...(params.stopLine ? { stopLine: true } : {}),
+            });
+          } catch (error) {
+            // The API's own words say "Stop the line, then move the product",
+            // which reads as an instruction to the agent; whether to interrupt
+            // the work is the person's call (PRO-2800).
+            if (error instanceof TaigaApiError && error.code === 'WORK_IN_FLIGHT') {
+              return toolError(
+                'WORK_IN_FLIGHT',
+                // The API's first sentence says what is in flight; its second ("Stop the line, then move the product")
+                // is the instruction this replaces.
+                `${withStop((error.apiMessage ?? 'Work is in flight on this product').split(/(?<=[.!?])\s/)[0]!)} Moving it now means stopping ` +
+                  'the line, which interrupts that work: ask the person, and pass stopLine: true only if they say so.',
+                error.details
+              );
+            }
+            throw error;
+          }
           return toolResult({
-            product: await productRow(client, moved.data as Row),
+            product: await productRow(client, moved.data),
             changed: moved.changed,
             previousFactoryId: moved.previousFactoryId,
             lineStopped: moved.lineStopped,
@@ -260,7 +258,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
             ...(params.ownsDeployment !== undefined ? { ownsDeployment: params.ownsDeployment } : {}),
             ...(params.deploymentNotes !== undefined ? { deploymentNotes: params.deploymentNotes } : {}),
           })
-        ).data as Row;
+        ).data;
         return toolResult(await productRow(client, product));
       })
   );
@@ -297,7 +295,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
         }
         const contradiction = notesWithNothingToDescribe(params);
         if (contradiction) return contradiction;
-        const updated = (await client.updateProduct(id, changes)).data as Row;
+        const updated = (await client.updateProduct(id, changes)).data;
         const warnings = missingNotesWarning(updated);
         return toolResult({ ...(await productRow(client, updated)), ...(warnings.length > 0 ? { warnings } : {}) });
       })
@@ -347,11 +345,11 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         try {
-          return toolResult(await productRow(client, (await client.completeSetup(params.productId)).data as Row));
+          return toolResult(await productRow(client, (await client.completeSetup(params.productId)).data));
         } catch (error) {
           // The refusal names what is missing; it does not say how a missing
           // document comes to exist, which is what the agent asks next.
-          if (!(error instanceof TaigaApiError) || error.details?.reason !== 'documents_incomplete') throw error;
+          if (!(error instanceof TaigaApiError) || error.details?.['reason'] !== 'documents_incomplete') throw error;
           return toolError(
             error.code ?? 'CONFLICT',
             `${withStop(error.apiMessage ?? 'Required documents are not published yet')} ${MISSING_DOCUMENTS_HOW}`,
@@ -372,9 +370,7 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
       annotations: OPERATE,
     },
     (params) =>
-      runTool(async () =>
-        toolResult(await productRow(client, (await client.reopenSetup(params.productId)).data as Row))
-      )
+      runTool(async () => toolResult(await productRow(client, (await client.reopenSetup(params.productId)).data)))
   );
 
   if (!client.hasCapability('products:read')) return;
@@ -396,8 +392,8 @@ export function registerSetupTools(server: McpServer, client: TaigaClient) {
     },
     (params) =>
       runTool(async () => {
-        const product = (await client.getProduct(params.productId)).data as Row;
-        if (!isImportedProduct(product as ProductSettingsView)) {
+        const product = (await client.getProduct(params.productId)).data;
+        if (!isImportedProduct(product)) {
           return toolError(
             'CONFLICT',
             'This product was started from scratch, so it has no import: the choice is made when a product is created.'

package/src/tools/summarize.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+import { pickFields } from './summarize.js';
+
+describe('pickFields', () => {
+  const rows: { id: string; name?: string; content?: string }[] = [
+    { id: 'a', name: 'A', content: 'the prose a list leaves out' },
+    { id: 'b' },
+  ];
+
+  it('keeps the named fields and leaves out one an item does not carry', () => {
+    expect(pickFields(rows, ['id', 'name'])).toEqual([{ id: 'a', name: 'A' }, { id: 'b' }]);
+  });
+
+  it('refuses a field the row type does not have', () => {
+    // The *_FIELDS lists are checked against their rows, so a misspelled field
+    // fails to compile instead of silently picking nothing (tsc covers tests).
+    // @ts-expect-error -- 'nmae' is not a field of the row.
+    expect(pickFields([{ id: 'a', name: 'A' }], ['id', 'nmae'])).toEqual([{ id: 'a' }]);
+  });
+});

package/src/tools/summarize.ts

@@ -3,12 +3,13 @@
  * fields a model needs to pick an item) and get tools return everything;
  * this is how a list drops the prose and the provenance trees.
  */
-export function pickFields<T extends Record<string, unknown>>(
-  items: T[],
-  fields: readonly string[]
-): Record<string, unknown>[] {
+export function pickFields<T extends object, K extends keyof T>(
+  items: readonly T[],
+  fields: readonly K[]
+): Partial<Pick<T, K>>[] {
   return items.map((item) => {
-    const picked: Record<string, unknown> = {};
+    // Partial: a field the item does not carry is left out, not set to undefined.
+    const picked: Partial<Pick<T, K>> = {};
     for (const field of fields) {
       if (field in item) picked[field] = item[field];
     }
@@ -26,7 +27,7 @@ export function page<T>(data: T[], nextCursor: string | null | undefined): { dat
  * carry, so "done with two unmet" shows in a list without reading the item.
  * Null while it has none (an unplanned initiative).
  */
-export function criteriaCounts(item: Record<string, unknown>): { met: number; total: number } | null {
+export function criteriaCounts(item: { acceptanceCriteria?: unknown }): { met: number; total: number } | null {
   const criteria = item.acceptanceCriteria;
   if (!Array.isArray(criteria) || criteria.length === 0) return null;
   const met = criteria.filter((c) => typeof c === 'object' && c !== null && (c as { met?: unknown }).met === true);
@@ -38,7 +39,10 @@ export function criteriaCounts(item: Record<string, unknown>): { met: number; to
  * does not carry `acceptanceCriteria` at all gets no count rather than a
  * null that would read as "has none".
  */
-export function itemRows(items: Record<string, unknown>[], fields: readonly string[]): Record<string, unknown>[] {
+export function itemRows<T extends { acceptanceCriteria?: unknown }, K extends keyof T>(
+  items: readonly T[],
+  fields: readonly K[]
+): (Partial<Pick<T, K>> & { criteria?: { met: number; total: number } | null })[] {
   return pickFields(items, fields).map((row, index) =>
     'acceptanceCriteria' in items[index]! ? { ...row, criteria: criteriaCounts(items[index]!) } : row
   );
@@ -53,18 +57,18 @@ const SEARCH_PAGE_LIMIT = 10;
  * told the person's word for a thing ("the Sandbox factory") otherwise pages
  * the whole list to find its ID. `more` is true when it stopped before the end.
  */
-export async function searchPages(
-  fetchPage: (cursor: string | undefined) => Promise<{ data: unknown[]; nextCursor: string | null }>,
+export async function searchPages<T>(
+  fetchPage: (cursor: string | undefined) => Promise<{ data: T[]; nextCursor: string | null }>,
   query: string,
-  text: (row: Record<string, unknown>) => unknown[],
+  text: (row: T) => unknown[],
   limit: number
-): Promise<{ rows: Record<string, unknown>[]; more: boolean }> {
+): Promise<{ rows: T[]; more: boolean }> {
   const needle = query.toLowerCase();
-  const rows: Record<string, unknown>[] = [];
+  const rows: T[] = [];
   let cursor: string | undefined;
   for (let index = 0; index < SEARCH_PAGE_LIMIT; index += 1) {
     const result = await fetchPage(cursor);
-    const page = result.data as Record<string, unknown>[];
+    const page = result.data;
     for (const [at, row] of page.entries()) {
       if (!text(row).some((value) => typeof value === 'string' && value.toLowerCase().includes(needle))) continue;
       rows.push(row);

package/src/tools/wait.ts

@@ -1,12 +1,15 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { BUILD_RUN_TERMINAL_STATUSES, resolveAutoBuild } from '@taiga/types';
+import type { BacklogItem, BacklogItemLifecycle, BuildRunWithContext } from '@taiga/types';
 import { z } from 'zod';
 import { idInput } from './inputs.js';
-import { TaigaApiError, type TaigaClient } from '../client.js';
+import { TaigaApiError, type TaigaClient, type WithoutTenant } from '../client.js';
 import { READ_ONLY } from './annotations.js';
 import { isNetworkFailure, runTool, toolResult } from './errors.js';
 import { SETTLED_JOB_STATUSES, jobReport } from './jobs.js';
 import { criteriaCounts, pickFields } from './summarize.js';
+import { situationOf } from './backlogs.js';
+import { readableRun } from './builds.js';
 
 /**
  * Waiting without a timer. A model in an editor has no clock: to learn that
@@ -43,7 +46,11 @@ const timeoutSeconds = z
       'many stop a call at 60 seconds.'
   );
 
-type Row = Record<string, unknown>;
+type Item = WithoutTenant<BacklogItem>;
+type Run = WithoutTenant<BuildRunWithContext>;
+
+/** The pull-request fields an initiative's latest run and a build run both carry. */
+type PullRequestFields = Pick<Run, 'prUrl' | 'prMerged' | 'prState'>;
 
 /** Why a wait ended: the condition held, it can no longer hold on its own, or time ran out. */
 type Verdict = { reached: true } | { reached: false; stoppedBecause: string } | null;
@@ -91,17 +98,17 @@ function isTransient(error: unknown): boolean {
  * it, which also keeps a client that resets its timeout on progress from
  * cutting the wait short.
  */
-async function waitFor(
-  read: (signal: AbortSignal) => Promise<Row>,
-  judge: (now: Row, first: Row) => Verdict,
+async function waitFor<T>(
+  read: (signal: AbortSignal) => Promise<T>,
+  judge: (now: T, first: T) => Verdict,
   timeoutMs: number,
   options: WaitOptions,
   progress: Progress
 ) {
   const started = Date.now();
   const deadline = started + timeoutMs;
-  let first: Row | null = null;
-  let now: Row | null = null;
+  let first: T | null = null;
+  let now: T | null = null;
   let verdict: Verdict = null;
   let failures = 0;
   for (let attempt = 0; !progress.signal.aborted; attempt += 1) {
@@ -156,7 +163,7 @@ const SETTLED_RUN: ReadonlySet<string> = new Set(BUILD_RUN_TERMINAL_STATUSES);
  * is open; the mirrored state and the merged latch say which. An unknown
  * state (null, just opened) counts as open.
  */
-function prIsOpen(run: Row): boolean {
+function prIsOpen(run: PullRequestFields): boolean {
   return typeof run.prUrl === 'string' && run.prUrl !== '' && run.prMerged !== true && run.prState !== 'closed';
 }
 
@@ -167,11 +174,13 @@ function prIsOpen(run: Row): boolean {
 const ITEM_CONDITIONS = ['changed', 'planned', 'your_turn', 'pr_open', 'run_settled', 'done'] as const;
 type ItemCondition = (typeof ITEM_CONDITIONS)[number];
 
-const latestBuildOf = (item: Row) => ((item.lifecycle as Row | undefined)?.latestBuild ?? null) as Row | null;
-const lifecycleOf = (item: Row) => (item.lifecycle ?? {}) as Row;
+// The API sends a lifecycle on every backlog item (backlogItemSchema); a
+// response without one reads as no lifecycle rather than failing the wait.
+const latestBuildOf = (item: Item) => item.lifecycle?.latestBuild ?? null;
+const lifecycleOf = (item: Item): Partial<BacklogItemLifecycle> => item.lifecycle ?? {};
 
 /** What "changed" compares: where the item is, whose turn it is and how its latest run stands. */
-function itemSignature(item: Row): string {
+function itemSignature(item: Item): string {
   const lifecycle = lifecycleOf(item);
   const run = latestBuildOf(item);
   return JSON.stringify([
@@ -209,7 +218,7 @@ interface GateDefault {
  * the gate cannot be resolved (no gate of its own, and the product's default
  * unreadable) the answer is unknown, and the wait says so rather than guess.
  */
-function personTurn(item: Row, gate: GateDefault): 'yes' | 'no' | 'unknown' {
+function personTurn(item: Item, gate: GateDefault): 'yes' | 'no' | 'unknown' {
   const lifecycle = lifecycleOf(item);
   if (lifecycle.turn !== 'you') return 'no';
   if (lifecycle.cta !== 'start_build') return 'yes';
@@ -219,7 +228,7 @@ function personTurn(item: Row, gate: GateDefault): 'yes' | 'no' | 'unknown' {
   return resolveAutoBuild({ initiative: own, product: product ?? true }) ? 'no' : 'yes';
 }
 
-function itemHolds(until: ItemCondition, item: Row, first: Row, gate: GateDefault): boolean {
+function itemHolds(until: ItemCondition, item: Item, first: Item, gate: GateDefault): boolean {
   const lifecycle = lifecycleOf(item);
   const run = latestBuildOf(item);
   switch (until) {
@@ -239,7 +248,7 @@ function itemHolds(until: ItemCondition, item: Row, first: Row, gate: GateDefaul
 }
 
 function judgeItem(until: ItemCondition, gate: GateDefault) {
-  return (item: Row, first: Row): Verdict => {
+  return (item: Item, first: Item): Verdict => {
     if (itemHolds(until, item, first, gate)) return { reached: true };
     // "changed" is how a model waits for a person to act on a flagged or
     // finished initiative, so none of the stops below apply to it.
@@ -276,9 +285,11 @@ function judgeItem(until: ItemCondition, gate: GateDefault) {
 }
 
 /** The initiative as a wait reports it: where it is, whose turn, its latest run and its criteria. */
-function itemReport(item: Row) {
+function itemReport(item: Item) {
   const run = latestBuildOf(item);
+  const situation = situationOf(item);
   return {
+    ...(situation ? { situation } : {}),
     ...pickFields(
       [item],
       ['id', 'title', 'state', 'planningStatus', 'needsHumanCause', 'needsHumanDetail', 'autoBuild']
@@ -313,14 +324,16 @@ const RUN_REPORT_FIELDS = [
   'prState',
   'prDraft',
   'prMerged',
+  'prNumber',
+  'baseBranch',
   'actions',
 ] as const;
 
-const runSignature = (run: Row) =>
+const runSignature = (run: Run) =>
   JSON.stringify([run.status, run.completedSteps, run.prUrl, run.prState, run.prMerged]);
 
 function judgeBuild(until: BuildCondition) {
-  return (run: Row, first: Row): Verdict => {
+  return (run: Run, first: Run): Verdict => {
     const holds =
       until === 'changed'
         ? runSignature(run) !== runSignature(first)
@@ -341,7 +354,7 @@ function judgeBuild(until: BuildCondition) {
 export function registerWaitTools(server: McpServer, client: TaigaClient, options: WaitOptions) {
   if (client.hasCapability('backlog:read')) {
     server.registerTool(
-      'taiga_wait_for_backlog_item',
+      'taiga_wait_for_initiative',
       {
         title: 'Wait for an initiative',
         description:
@@ -357,7 +370,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
           'settled answers run_settled at once; item is null when not even the first read answered in time. ' +
           'Planning takes minutes and a build up to an hour.',
         inputSchema: z.object({
-          itemId: idInput('backlog item', 'taiga_list_backlog_items (query finds one by title) gives it'),
+          initiativeId: idInput('initiative', 'taiga_list_initiatives (query finds one by title) gives it'),
           until: z.enum(ITEM_CONDITIONS).describe('What to wait for'),
           timeoutSeconds,
         }),
@@ -367,14 +380,14 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
         runTool(async () => {
           const gate: GateDefault = { product: undefined };
           const read = async (signal: AbortSignal) => {
-            const item = (await client.getBacklogItem(params.itemId, signal)).data as Row;
+            const item = (await client.getBacklogItem(params.initiativeId, signal)).data;
             // The product's default, once, when this initiative has no gate of its own to answer with.
             if (gate.product === undefined && typeof item.autoBuild !== 'boolean') {
               gate.product = client.hasCapability('products:read')
                 ? await client
                     .getProduct(String(item.productId), signal)
                     .then((p) => {
-                      const value = (p.data as { autoBuild?: unknown }).autoBuild;
+                      const value = p.data.autoBuild;
                       return typeof value === 'boolean' ? value : true;
                     })
                     // Not allowed, or gone: unknown for good. Anything transient
@@ -406,7 +419,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
 
   if (client.hasCapability('products:read')) {
     server.registerTool(
-      'taiga_wait_for_build',
+      'taiga_wait_for_run',
       {
         title: 'Wait for a run',
         description:
@@ -418,7 +431,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
           'call again to keep waiting. Conditions are states: a run already settled answers settled at once; run ' +
           'is null when not even the first read answered in time.',
         inputSchema: z.object({
-          buildId: idInput('build run', 'taiga_list_builds gives it'),
+          runId: idInput('run', 'taiga_list_runs gives it'),
           until: z.enum(BUILD_CONDITIONS).describe('What to wait for'),
           timeoutSeconds,
         }),
@@ -427,7 +440,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
       (params, ctx) =>
         runTool(async () => {
           const result = await waitFor(
-            async (signal) => (await client.getBuildRun(params.buildId, signal)).data as Row,
+            async (signal) => (await client.getBuildRun(params.runId, signal)).data,
             judgeBuild(params.until),
             (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
             options,
@@ -441,7 +454,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
           return toolResult({
             until: params.until,
             ...outcome,
-            run: now ? pickFields([now], RUN_REPORT_FIELDS)[0] : null,
+            run: now ? readableRun(pickFields([now], RUN_REPORT_FIELDS)[0]!) : null,
           });
         })
     );
@@ -466,7 +479,7 @@ export function registerWaitTools(server: McpServer, client: TaigaClient, option
       (params, ctx) =>
         runTool(async () => {
           const result = await waitFor(
-            async (signal) => (await client.getAgentJob(params.jobId, signal)).data as Row,
+            async (signal) => (await client.getAgentJob(params.jobId, signal)).data,
             (job) => (SETTLED_JOB_STATUSES.has(String(job.status)) ? { reached: true } : null),
             (params.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
             options,