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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.19.0-rc.452",
+  "version": "0.20.0-dev.454",
   "description": "MCP server for Taiga -- gives AI assistants access to documents and products",
   "type": "module",
   "main": "./dist/index.js",

package/src/server.integration.test.ts

@@ -266,8 +266,12 @@ async function connectServer(taigaClient: TaigaClient, wait?: WaitOptions) {
 }
 
 /** Extract sorted tool names from a listTools response. */
+/** The tools a key was given, beside taiga_whoami, which comes with any of them (PRO-2800). */
 function toolNames(tools: { name: string }[]) {
-  return tools.map((t) => t.name).sort();
+  return tools
+    .map((t) => t.name)
+    .filter((name) => name !== 'taiga_whoami')
+    .sort();
 }
 
 /** Extract parsed JSON from the first text content block of a tool call result. */
@@ -2030,9 +2034,9 @@ describe('MCP server integration', () => {
       expect(bundle.policies).toEqual([
         { type: 'policy_security', name: 'Security Policy', version: 3, sections: ['summary', 'scope'] },
       ]);
-      expect(bundle.backlog.items.map((row: { id: string }) => row.id)).toEqual([ITEM_ID]);
-      expect(bundle.backlog.items[0]).not.toHaveProperty('description');
-      expect(bundle.backlog.truncated).toBe(false);
+      expect(bundle.initiatives.items.map((row: { id: string }) => row.id)).toEqual([ITEM_ID]);
+      expect(bundle.initiatives.items[0]).not.toHaveProperty('description');
+      expect(bundle.initiatives.truncated).toBe(false);
       expect(bundle.repositories).toEqual({
         items: [
           {
@@ -2046,7 +2050,7 @@ describe('MCP server integration', () => {
         ],
         truncated: false,
       });
-      expect(bundle.builds).toEqual([
+      expect(bundle.runs).toEqual([
         {
           id: BUILD_ID,
           runNumber: 1,
@@ -2057,13 +2061,17 @@ describe('MCP server integration', () => {
         },
       ]);
       // PRO-2800: "how does it stand" in the same call, as counts.
-      expect(bundle.attention).toEqual({ open: 3, byKind: { review_pr: 2, setup_secret: 1 }, snoozed: 1 });
+      expect(bundle.actionRequired).toEqual({ open: 3, byKind: { review_pr: 2, setup_secret: 1 }, snoozed: 1 });
       expect(bundle.maintenance).toEqual({
         openFindings: 1,
         bySeverity: { critical: 0, high: 1 },
         lastSweep: { status: 'completed', completedAt: '2026-10-01T00:00:00.000Z' },
       });
-      expect(bundle.standing).toEqual({ openViolations: 3, bySeverity: { critical: 1, high: 2 }, controlsViolated: 2 });
+      expect(bundle.policyStanding).toEqual({
+        openViolations: 3,
+        bySeverity: { critical: 1, high: 2 },
+        controlsViolated: 2,
+      });
       expect(bundle.notGranted).toEqual([]);
       expect(bundle.unavailable).toEqual({});
     });
@@ -2078,7 +2086,7 @@ describe('MCP server integration', () => {
       expect(bundle.notGranted).toEqual([
         'factory (needs factories:read)',
         'policies (needs tenant:documents:read)',
-        'backlog (needs backlog:read)',
+        'initiatives (needs backlog:read)',
       ]);
       expect(bundle).not.toHaveProperty('factory');
       expect(bundle).not.toHaveProperty('policies');
@@ -2098,9 +2106,9 @@ describe('MCP server integration', () => {
         await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
       );
 
-      expect(bundle.unavailable).toEqual({ backlog: '429 RATE_LIMITED: Slow down' });
-      expect(bundle).not.toHaveProperty('backlog');
-      expect(bundle.builds).toHaveLength(1);
+      expect(bundle.unavailable).toEqual({ initiatives: '429 RATE_LIMITED: Slow down' });
+      expect(bundle).not.toHaveProperty('initiatives');
+      expect(bundle.runs).toHaveLength(1);
     });
 
     it('should read every backlog page, since the open items are the newest and the list is oldest first', async () => {
@@ -2124,7 +2132,7 @@ describe('MCP server integration', () => {
         await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
       );
 
-      expect(bundle.backlog.items.map((row: { title: string }) => row.title)).toEqual(['Add login', 'Newest']);
+      expect(bundle.initiatives.items.map((row: { title: string }) => row.title)).toEqual(['Add login', 'Newest']);
     });
 
     it('should list an item once when it moved between the two status reads', async () => {
@@ -2141,8 +2149,8 @@ describe('MCP server integration', () => {
         await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
       );
 
-      expect(bundle.backlog.items).toHaveLength(1);
-      expect(bundle.backlog.truncated).toBe(false);
+      expect(bundle.initiatives.items).toHaveLength(1);
+      expect(bundle.initiatives.truncated).toBe(false);
       const statuses = fetchSpy.mock.calls
         .map((c: unknown[]) => new URL(c[0] as string))
         .filter((u: URL) => u.pathname.endsWith('/backlog'))
@@ -2170,10 +2178,10 @@ describe('MCP server integration', () => {
       );
 
       // Ten pages per open status, two statuses.
-      expect(bundle.backlog.items).toHaveLength(20);
-      expect(bundle.backlog.truncated).toBe(true);
+      expect(bundle.initiatives.items).toHaveLength(20);
+      expect(bundle.initiatives.truncated).toBe(true);
       // The list pages oldest first: past the cap, the newest were never read, and the bundle says so.
-      expect(bundle.backlog.note).toContain('only the oldest of them were read');
+      expect(bundle.initiatives.note).toContain('only the oldest of them were read');
     });
 
     it('should carry the newest fifty open items across both statuses and say the backlog is truncated', async () => {
@@ -2200,10 +2208,10 @@ describe('MCP server integration', () => {
         await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
       );
 
-      expect(bundle.backlog.items).toHaveLength(50);
-      expect(bundle.backlog.items[0].title).toBe('Item 11');
-      expect(bundle.backlog.items.at(-1).title).toBe('Newest');
-      expect(bundle.backlog.truncated).toBe(true);
+      expect(bundle.initiatives.items).toHaveLength(50);
+      expect(bundle.initiatives.items[0].title).toBe('Item 11');
+      expect(bundle.initiatives.items.at(-1).title).toBe('Newest');
+      expect(bundle.initiatives.truncated).toBe(true);
     });
 
     it('should carry the two documents as their outline when asked for it', async () => {
@@ -3445,7 +3453,7 @@ describe('MCP server integration', () => {
       const call = fetchSpy.mock.calls.find((c: unknown[]) => (c[0] as string).endsWith('/resume'))!;
       expect((call[1] as RequestInit).method).toBe('POST');
       expect((call[1] as RequestInit).body).toBeNull();
-      expect(outcomeOf(result).lifecycle).toEqual(resumed.lifecycle);
+      expect(outcomeOf(result).lifecycle).toEqual(asSeen(resumed.lifecycle));
     });
 
     it('should read the active plan with its steps and say when there is none', async () => {
@@ -4336,7 +4344,7 @@ describe('MCP server integration', () => {
         })
       );
 
-      expect(result).toMatchObject({ reached: true, item: { latestBuild: { prState: 'closed' } } });
+      expect(result).toMatchObject({ reached: true, item: { latestRun: { prState: 'closed' } } });
     });
 
     it('should end the read in flight when the call is cancelled', async () => {
@@ -4473,7 +4481,7 @@ describe('MCP server integration', () => {
       );
 
       // Not stopped at the landed plan: the open gate builds it without anyone.
-      expect(result).toMatchObject({ reached: true, item: { latestBuild: { prState: 'open' } } });
+      expect(result).toMatchObject({ reached: true, item: { latestRun: { prState: 'open' } } });
     });
 
     it("should take a landed plan for a person's turn when the product's closed gate holds it, reading the product once", async () => {
@@ -6430,7 +6438,7 @@ describe('what the agent review found (PRO-2759)', () => {
     expect(parseToolResult(item)).toEqual({
       error: 'NOT_FOUND',
       message:
-        "Backlog item not found. taiga_list_initiatives lists a product's initiatives with their IDs; a run or " +
+        "Initiative not found. taiga_list_initiatives lists a product's initiatives with their IDs; a run or " +
         'plan ID is not one.',
     });
 
@@ -6488,7 +6496,7 @@ describe('what the agent review found (PRO-2759)', () => {
 
     expect(noPlan.message).toContain('taiga_plan_again asks for a new one');
     expect(noItem.message).toBe(
-      "Backlog item not found. taiga_list_initiatives lists a product's initiatives with their IDs; a run or " +
+      "Initiative not found. taiga_list_initiatives lists a product's initiatives with their IDs; a run or " +
         'plan ID is not one.'
     );
   });
@@ -6616,8 +6624,8 @@ describe('what the agent review found (PRO-2759)', () => {
     expect(product.readiness).toEqual({
       ready: false,
       repository: { linked: false },
-      import: 'not started',
-      missingDocuments: ['Specification', 'Architecture'],
+      import: 'pending',
+      missingDocuments: ['specification', 'architecture'],
       openChecks: [],
       nextStep:
         'Link its repository (taiga_list_linkable_repositories, then taiga_link_repository), then taiga_start_import.',
@@ -6813,10 +6821,36 @@ describe('what the agent review found (PRO-2759)', () => {
     expect(Object.keys(standing)[0]).toBe('summary');
     expect(standing.summary).toEqual({
       controls: 1,
+      controlsInPolicies: 2,
+      controlsWithNothingRecorded: 1,
       violations: 2,
       bySeverity: { high: 1, critical: 1 },
       resolvedViolations: 1,
     });
+    expect(standing).not.toHaveProperty('note');
+  });
+
+  it('says a never-assessed standing is no all-clear (PRO-2800)', async () => {
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read'],
+      routes: {
+        [`GET /v1/products/${PRODUCT_ID}/maintenance/policies`]: {
+          data: {
+            productId: PRODUCT_ID,
+            hasPolicies: true,
+            assessment: { state: 'never' },
+            controls: [],
+            divergences: [],
+          },
+        },
+      },
+    });
+
+    const standing = parseToolResult(
+      await client.callTool({ name: 'taiga_get_policy_standing', arguments: { productId: PRODUCT_ID } })
+    );
+
+    expect(standing.note).toMatch(/^Never assessed: .* nothing here is an all-clear/);
   });
 });
 
@@ -7039,12 +7073,11 @@ describe('what the second agent review found (PRO-2778, PRO-2780)', () => {
     for (const tool of tools) {
       const notes = tool.annotations ?? {};
       const description = tool.description ?? '';
-      if (notes.readOnlyHint) expect(description, tool.name).not.toMatch(/^(Writes\.|Acts on paid)/);
-      else if (notes.destructiveHint)
-        expect(description, tool.name).toMatch(/^Acts on paid or shared work: ask the person first\. /);
+      if (notes.readOnlyHint) expect(description, tool.name).not.toMatch(/^(Writes\.|Ask first:)/);
+      else if (notes.destructiveHint) expect(description, tool.name).toMatch(/^Ask first: paid or shared work\. /);
       else expect(description, tool.name).toMatch(/^Writes\. /);
     }
-    expect(tools.find((t) => t.name === 'taiga_queue_initiative')!.description).toMatch(/^Acts on paid/);
+    expect(tools.find((t) => t.name === 'taiga_queue_initiative')!.description).toMatch(/^Ask first:/);
     expect(tools.find((t) => t.name === 'taiga_create_factory')!.description).toMatch(/^Writes\. /);
   });
 
@@ -7089,6 +7122,219 @@ describe('what the third agent review found (PRO-2800)', () => {
     vi.restoreAllMocks();
   });
 
+  it('says who the key acts as and which of its tools write', async () => {
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read', 'backlog:read', 'backlog:write', 'products:write'],
+    });
+
+    const me = parseToolResult(await client.callTool({ name: 'taiga_whoami', arguments: {} }));
+
+    expect(me.role).toBeTypeOf('string');
+    expect(me.capabilities).toEqual(expect.arrayContaining(['products:read', 'backlog:write']));
+    expect(me.tools.reads).toContain('taiga_get_product_context');
+    expect(me.tools.askFirst).toContain('taiga_queue_initiative');
+    expect(me.tools.reads).not.toContain('taiga_whoami');
+  });
+
+  it('marks a pull request review that no longer stands, and counts those in the summary', async () => {
+    const RUN_2 = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4e02';
+    const ITEM_2 = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4e03';
+    const review = (id: string, subjectId: string) => ({
+      id,
+      productId: PRODUCT_ID,
+      productName: 'Web',
+      kind: 'review_pr',
+      subjectType: 'build_run',
+      subjectId,
+      status: 'open',
+      createdAt: new Date().toISOString(),
+    });
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read', 'backlog:read'],
+      routes: {
+        'GET /v1/inbox': { data: [review('i1', BUILD_ID), review('i2', RUN_2)], nextCursor: null },
+        [`GET /v1/builds/${BUILD_ID}`]: {
+          data: { id: BUILD_ID, prState: 'open', prMerged: false, backlogItemId: ITEM_ID },
+        },
+        [`GET /v1/backlog/${ITEM_ID}`]: { data: { id: ITEM_ID, state: 'build', status: 'in_progress' } },
+        [`GET /v1/builds/${RUN_2}`]: { data: { id: RUN_2, prState: 'open', prMerged: false, backlogItemId: ITEM_2 } },
+        [`GET /v1/backlog/${ITEM_2}`]: { data: { id: ITEM_2, state: 'canceled', status: 'canceled' } },
+      },
+    });
+
+    const list = parseToolResult(await client.callTool({ name: 'taiga_list_action_required', arguments: {} }));
+
+    expect(list.data[0]).not.toHaveProperty('stale');
+    expect(list.data[1].stale).toBe('its initiative was canceled; the pull request is still open on the forge');
+    expect(list.summary).toEqual([
+      { productId: PRODUCT_ID, product: 'Web', open: 2, byKind: { review_pr: 2 }, stale: 1 },
+    ]);
+  });
+
+  it("names a handback's own next step, counts rounds in words, and keeps a multi-line error to its first line", async () => {
+    const base = {
+      productId: PRODUCT_ID,
+      completedSteps: 2,
+      totalSteps: 3,
+      prNumber: 5,
+      prUrl: 'https://x/5',
+      prDraft: false,
+    };
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read'],
+      routes: {
+        [`/v1/products/${PRODUCT_ID}/builds`]: {
+          data: [
+            { ...base, id: 'a', status: 'needs_review', reviewEscalation: { reason: 'ci_never_settled' } },
+            { ...base, id: 'b', status: 'needs_review', reviewEscalation: { reason: 'ci_fix_cap', rounds: 1 } },
+            {
+              ...base,
+              id: 'c',
+              status: 'failed',
+              prUrl: null,
+              prNumber: null,
+              error: 'TypeError: boom\n    at x (y.js:1)',
+            },
+          ],
+          nextCursor: null,
+        },
+      },
+    });
+
+    const runs = parseToolResult(
+      await client.callTool({ name: 'taiga_list_runs', arguments: { productId: PRODUCT_ID } })
+    ).data as Record<string, unknown>[];
+
+    expect(runs[0]!['outcome']).toMatch(/look at what is still running or queued in CI/);
+    expect(runs[1]!['outcome']).toMatch(/CI is still failing after 1 automatic round\./);
+    expect(runs[2]!['outcome']).toBe('Failed: TypeError: boom (2 of 3 steps done).');
+    // A row says the handback in its outcome; the full read keeps the record.
+    expect(runs[0]).not.toHaveProperty('reviewEscalation');
+  });
+
+  it('counts a review it could not check as unchecked, not live', async () => {
+    const { client } = await bootMcpPair({
+      // products:read alone: the run is readable, its initiative is not.
+      capabilities: ['products:read'],
+      routes: {
+        'GET /v1/inbox': {
+          data: [
+            {
+              id: 'i1',
+              productId: PRODUCT_ID,
+              kind: 'review_pr',
+              subjectType: 'build_run',
+              subjectId: BUILD_ID,
+              status: 'open',
+              createdAt: new Date().toISOString(),
+            },
+          ],
+          nextCursor: null,
+        },
+        [`GET /v1/builds/${BUILD_ID}`]: { data: { id: BUILD_ID, prState: 'open', backlogItemId: ITEM_ID } },
+      },
+    });
+
+    const list = parseToolResult(await client.callTool({ name: 'taiga_list_action_required', arguments: {} }));
+
+    expect(list.data[0]).not.toHaveProperty('stale');
+    expect(list.staleNote).toMatch(/^1 pull request review was not checked for staleness/);
+  });
+
+  it('names factories past the first page of them', async () => {
+    const FACTORY_2 = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4e10';
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read', 'factories:read'],
+      routes: {
+        'GET /v1/products': {
+          data: [{ id: PRODUCT_ID, name: 'Web', slug: 'web', factoryId: FACTORY_2 }],
+          nextCursor: null,
+        },
+        'GET /v1/factories': (url: string) => {
+          const second = new URL(url).searchParams.get('cursor') === 'p2';
+          const body = second
+            ? { data: [{ id: FACTORY_2, name: 'Second' }], nextCursor: null }
+            : { data: [{ id: FACTORY_ID, name: 'First' }], nextCursor: 'p2' };
+          return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+        },
+      },
+    });
+
+    const products = parseToolResult(await client.callTool({ name: 'taiga_list_products', arguments: {} }));
+
+    expect(products.data[0].factoryName).toBe('Second');
+  });
+
+  it('says why the agent handed a run back, where the initiative and the line say whose turn it is', async () => {
+    const item = {
+      id: ITEM_ID,
+      title: 'HTTPS',
+      lifecycle: {
+        turn: 'you',
+        stage: 'in_review',
+        cta: 'review_pr',
+        planFailureCause: null,
+        latestBuild: {
+          id: BUILD_ID,
+          status: 'needs_review',
+          prNumber: 29,
+          reviewEscalation: { reason: 'ci_fix_stalled', failingChecks: [{ name: 'secret-scan', url: null }] },
+        },
+      },
+    };
+    const { client } = await bootMcpPair({
+      capabilities: ['backlog:read'],
+      routes: { [`GET /v1/backlog/${ITEM_ID}`]: { data: item } },
+    });
+
+    const got = parseToolResult(
+      await client.callTool({ name: 'taiga_get_initiative', arguments: { initiativeId: ITEM_ID } })
+    );
+
+    expect(got.situation).toContain(
+      'handed back because CI is still failing on secret-scan, and the last fix round changed nothing'
+    );
+    expect(got.lifecycle.latestRun.id).toBe(BUILD_ID);
+  });
+
+  it('reads the sections that state a policy control id', async () => {
+    const { client } = await bootMcpPair({
+      capabilities: ALL_CAPABILITIES,
+      routes: {
+        'GET /v1/tenants/current/documents/policy_security': {
+          data: {
+            id: 'doc-1',
+            type: 'policy_security',
+            version: 1,
+            isDraft: false,
+            data: {
+              version: '1.0.0',
+              sections: {
+                scope: { content: 'All systems.' },
+                secretsManagement: { content: '| SEC-5.1 | Secrets in a vault |\n| SEC-5.10 | Rotate |' },
+                logging: { content: '| SEC-5.10 | Log access |' },
+                appendix: { content: 'See SEC-5.1A and SEC-5.1-appendix, and SEC-5.1.2.' },
+                summary: { content: 'Secrets follow SEC-5.1.' },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    const doc = parseToolResult(
+      await client.callTool({
+        name: 'taiga_get_document',
+        arguments: { type: 'policy_security', sections: ['SEC-5.1', 'SEC-9.9'] },
+      })
+    );
+
+    // A whole id only, and a sentence's full stop after it is still the id.
+    expect(Object.keys(doc.data.sections).sort()).toEqual(['secretsManagement', 'summary']);
+    expect(doc.controls).toEqual({ 'SEC-5.1': ['secretsManagement', 'summary'] });
+    expect(doc.unknownSections).toEqual(['SEC-9.9']);
+  });
+
   it('loads the three entry tools upfront in Claude Code, and only those', async () => {
     const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
 
@@ -7185,6 +7431,43 @@ describe('what the third agent review found (PRO-2800)', () => {
     expect(archive.data[0].waitingDays).toBe(2);
   });
 
+  it("reads a draft product's links once for the context's repositories and its readiness", async () => {
+    const draft = { id: PRODUCT_ID, name: 'Web', slug: 'web', status: 'draft', factoryId: FACTORY_ID, settings: {} };
+    const { client, fetchSpy } = await bootMcpPair({
+      capabilities: ['products:read'],
+      routes: {
+        [`GET /v1/products/${PRODUCT_ID}`]: { data: { ...draft, discoveryStep: 'documents' } },
+        [`GET /v1/products/${PRODUCT_ID}/repositories`]: { data: [], nextCursor: null },
+      },
+    });
+
+    const bundle = parseToolResult(
+      await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+    );
+
+    expect(bundle.product.readiness.repository).toEqual({ linked: false });
+    expect(bundle.repositories.items).toEqual([]);
+    const reads = fetchSpy.mock.calls.filter((call: unknown[]) =>
+      new URL(call[0] as string).pathname.endsWith('/repositories')
+    );
+    expect(reads).toHaveLength(1);
+  });
+
+  it("keeps a stopped run's draft state when it opened a pull request", async () => {
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read', 'products:write'],
+      routes: {
+        [`POST /v1/builds/${BUILD_ID}/stop`]: {
+          data: { id: BUILD_ID, status: 'stopped', prNumber: 4, prUrl: 'https://x/4', prDraft: true, actions: [] },
+        },
+      },
+    });
+
+    const stopped = parseToolResult(await client.callTool({ name: 'taiga_stop_run', arguments: { runId: BUILD_ID } }));
+
+    expect(stopped.prDraft).toBe(true);
+  });
+
   it('lists a variable filed under two categories once, naming the other record', async () => {
     const task = (id: string, category: string, key: string | null) => ({
       id,
@@ -7211,6 +7494,8 @@ describe('what the third agent review found (PRO-2800)', () => {
 
     expect(tasks.data.map((row: { id: string }) => row.id)).toEqual(['t1', 't2']);
     expect(tasks.data[0].alsoFiledAs).toEqual([{ id: 't3', category: 'env_var', title: 'Set JWT_SECRET' }]);
+    // Three records folded into two rows: the page says so beside the rows.
+    expect(tasks.recordsOnPage).toBe(3);
   });
 
   it('leads a variable with its open record when an older one is done', async () => {
@@ -7286,6 +7571,24 @@ describe('what the third agent review found (PRO-2800)', () => {
               prUrl: 'https://x/8',
               baseBranch: 'main',
             },
+            {
+              ...base,
+              id: 'r7',
+              status: 'needs_review',
+              prNumber: 29,
+              prUrl: 'https://x/29',
+              reviewEscalation: { reason: 'ci_fix_stalled', failingChecks: [{ name: 'secret-scan', url: null }] },
+            },
+            {
+              ...base,
+              id: 'r8',
+              status: 'failed',
+              failedReason: 'dispatch_rejected',
+              error: 'The engineer environment is unavailable: the instance terminated while starting. Retry later.',
+              completedSteps: 0,
+              totalSteps: 3,
+              prUrl: null,
+            },
           ],
           nextCursor: null,
         },
@@ -7300,9 +7603,18 @@ describe('what the third agent review found (PRO-2800)', () => {
       ['rejected', 'PR #28 was closed without merging, so the work did not land.'],
       ['succeeded', 'Merged: PR #7 is in main.'],
       ['failed', 'Failed: agent_error (2 of 6 steps done).'],
-      ['gated', 'Waiting for a person to review and merge PR #9.'],
+      ['gated', 'Waiting for a person to review and merge PR #9, still a draft.'],
       ['in_flight', 'Running: hardening: running the security scanners and fixing what they find (6 of 6 steps done).'],
       ['succeeded', 'Merged: PR #8 is in main.'],
+      [
+        'gated',
+        'Handed back to a person: CI is still failing on secret-scan, and the last fix round changed nothing. ' +
+          'PR #29, still a draft, waits for them to fix it by hand or review it back to the agent.',
+      ],
+      [
+        'failed',
+        'Failed: The engineer environment is unavailable: the instance terminated while starting (0 of 3 steps done).',
+      ],
     ]);
     expect(runs[0]).toHaveProperty('prDraft', false);
     expect(runs[2]).not.toHaveProperty('prDraft');

package/src/tools/autonomy.ts

@@ -64,7 +64,7 @@ export function registerAutonomyTools(server: McpServer, client: TaigaClient) {
       {
         title: "Set whether an initiative's pull request merges on its own",
         description:
-          "An initiative's own switch for merging on its own: true lets its pull request merge itself once the " +
+          "Set whether one initiative's pull request merges on its own: true lets its pull request merge itself once the " +
           "repository's own rules pass (required checks, reviews, a code reviewer you made Taiga wait for); false " +
           "makes it wait for a person; null follows the product's default. The final word within what the " +
           'organization and factories allow: where either has turned autonomous merge off, true changes nothing. ' +

package/src/tools/backlogs.ts

@@ -20,7 +20,7 @@ import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
 import { jobReport } from './jobs.js';
 import { requestPrompt } from './request-prompt.js';
 import { queueView } from './queue.js';
-import { landedDisposition } from './builds.js';
+import { handbackNextStep, handbackSaid, landedDisposition } from './builds.js';
 import {
   SEARCH_NOTE,
   SEARCH_PAGE_SIZE,
@@ -139,6 +139,9 @@ export function situationOf(item: Record<string, unknown>): string | null {
       ? RUN_STANDS[landedDisposition(build.status as BuildRunStatus, build.prMerged === true)]
       : build.status;
     stage += `; its latest run ${said}${pr}`;
+    // Handed back: what the agent could not get past, which "in review" alone hides.
+    const handback = handbackSaid((build as { reviewEscalation?: unknown }).reviewEscalation);
+    if (handback) stage += `, handed back because ${handback}`;
   }
   parts.push(`${stage}.`);
   if (typeof item['needsHumanCause'] === 'string') {
@@ -152,7 +155,13 @@ export function situationOf(item: Record<string, unknown>): string | null {
     if (why) parts.push(`The line stopped on it: ${why}.`);
   }
   const turn = life.turn === 'you' ? "A person's turn" : life.turn === 'agent' ? "The agent's turn" : null;
-  const move = typeof life.cta === 'string' ? CTA_MOVE[life.cta] : undefined;
+  const handedBack = handbackSaid((build as { reviewEscalation?: unknown } | null | undefined)?.reviewEscalation);
+  const move =
+    life.cta === 'review_pr' && handedBack
+      ? `a person should ${handbackNextStep((build as { reviewEscalation?: unknown }).reviewEscalation)}`
+      : typeof life.cta === 'string'
+        ? CTA_MOVE[life.cta]
+        : undefined;
   if (life.cta === 'view_pr') parts.push(`Nothing to do: ${move}.`);
   else if (turn && move) parts.push(`${turn}: ${move}.`);
   else if (turn) parts.push(`${turn}.`);
@@ -295,7 +304,7 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
     {
       title: 'List initiatives',
       description:
-        "List a product's initiatives, its backlog: titles, category, status, where each one is on the " +
+        "List a product's initiatives (its backlog): titles, category, status, where each one is on the " +
         'line (backlog, todo, queue, plan, build, done), situation (where it stands and what moves it on, in a ' +
         'sentence) and criteria, how many of its acceptance criteria are met ' +
         '(null before it is planned; met counts the criteria the agent confirmed with evidence or a person checked ' +
@@ -457,7 +466,7 @@ function registerMove(server: McpServer, client: TaigaClient) {
     {
       title: 'Move initiative on the board',
       description:
-        'Move an initiative on the board, or order it within a column: backlog and todo are yours and the line ' +
+        'Move an initiative on the board, take it off the line, or order it within a column: backlog and todo are yours and the line ' +
         'never moves an initiative out of them; queue puts it in the line (taiga_queue_initiative says more); ' +
         'done and canceled finish it by hand. The queue is the only way to start work: there is no "plan this ' +
         'now", and nothing is moved into Build by a person. Moving an initiative out of Build stops the plan ' +
@@ -678,7 +687,7 @@ function registerResume(server: McpServer, client: TaigaClient) {
     {
       title: 'Resume initiative',
       description:
-        'Resume an initiative the line stopped on, which is when needsHumanCause is set (the line sets it): a ' +
+        'Carry on an initiative the line stopped on, which is when needsHumanCause is set (the line sets it): a ' +
         'failed or cancelled plan is planned again, a stopped or failed run resumes from its first unfinished ' +
         'part (the steps already committed are kept), a refused build start is cleared and retried. This is the ' +
         'way to carry work on: a run is the record of an attempt, and decisions about the work are made on the ' +