@taiga-ai/mcp-server 0.11.0 → 0.12.0-dev.417

package/src/server.integration.test.ts

@@ -36,6 +36,7 @@ const ALL_TOOL_NAMES = [
   'taiga_get_product',
   'taiga_get_product_context',
   'taiga_get_product_document',
+  'taiga_get_queue',
   'taiga_list_backlog_items',
   'taiga_list_builds',
   'taiga_list_documents',
@@ -51,9 +52,12 @@ const ALL_TOOL_NAMES = [
   'taiga_resolve_product',
   'taiga_resume_backlog_item',
   'taiga_resume_build',
+  'taiga_set_auto_build',
   'taiga_stop_build',
   'taiga_update_document',
   'taiga_update_factory_document',
+  'taiga_wait_for_backlog_item',
+  'taiga_wait_for_build',
 ];
 
 const PRODUCT_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c';
@@ -100,10 +104,13 @@ function sentBody(fetchSpy: ReturnType<typeof vi.fn>, method: string, pathPart:
 
 /** What the API answers when it refuses: the status and the error envelope its error handler sends. */
 class Refusal {
-  constructor(
-    readonly status: number,
-    readonly body: { error: string; code: string; message: string }
-  ) {}
+  readonly status: number;
+  readonly body: { error: string; code: string; message: string };
+
+  constructor(status: number, body: { error: string; code: string; message: string }) {
+    this.status = status;
+    this.body = body;
+  }
 }
 const refusal = (status: number, code: string, message: string) => new Refusal(status, { error: code, code, message });
 
@@ -114,8 +121,8 @@ function makeFetchRouter(routes: Record<string, unknown>) {
     // Most specific first: a route keyed with its query string (the two
     // document timelines share a path) wins over one keyed by path alone.
     const body = routes[`${method} ${path}${search}`] ?? routes[`${method} ${path}`] ?? routes[path];
-    // A route given as a function answers or throws like fetch would.
-    if (typeof body === 'function') return (body as () => unknown)();
+    // A route given as a function answers or throws like fetch would, and sees the request.
+    if (typeof body === 'function') return (body as (url: string, init: RequestInit) => unknown)(url, init);
     // A refusal the API would send, with its status: `refusal(409, {...})`.
     if (body instanceof Refusal) {
       return {
@@ -178,7 +185,8 @@ async function bootMcpPair(opts: { capabilities: string[]; routes?: Record<strin
   await taigaClient.introspect();
 
   const server = new McpServer({ name: 'taiga-test', version: '0.0.1' });
-  registerAllTools(server, taigaClient);
+  // Waits poll every few milliseconds here, not every few seconds.
+  registerAllTools(server, taigaClient, { wait: { pollIntervalMs: 5 } });
 
   const client = new Client({ name: 'test-client', version: '0.0.1' });
   const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
@@ -355,8 +363,15 @@ describe('MCP server integration', () => {
         'taiga_get_product_document',
         'taiga_list_builds',
         'taiga_get_build',
+        'taiga_get_queue',
+        'taiga_wait_for_build',
+      ],
+      'backlog:read': [
+        'taiga_list_backlog_items',
+        'taiga_get_backlog_item',
+        'taiga_get_plan',
+        'taiga_wait_for_backlog_item',
       ],
-      'backlog:read': ['taiga_list_backlog_items', 'taiga_get_backlog_item', 'taiga_get_plan'],
       'factories:read': ['taiga_list_factories', 'taiga_list_factory_documents', 'taiga_get_factory_document'],
       'tenant:documents:read': ['taiga_list_documents', 'taiga_get_document'],
     };
@@ -365,7 +380,7 @@ describe('MCP server integration', () => {
       'factories:read factories:documents:write': ['taiga_update_factory_document', 'taiga_publish_factory_document'],
       'backlog:write': ['taiga_create_backlog_item', 'taiga_move_backlog_item'],
       'backlog:write products:write': ['taiga_queue_backlog_item'],
-      'products:write': ['taiga_resume_backlog_item'],
+      'products:write': ['taiga_resume_backlog_item', 'taiga_set_auto_build'],
       'backlog:read products:write': ['taiga_approve_plan', 'taiga_reject_plan'],
       'products:read products:write': ['taiga_stop_build', 'taiga_resume_build'],
     };
@@ -1058,7 +1073,7 @@ describe('MCP server integration', () => {
       expect(sentUrl(fetchSpy, '/builds').searchParams.get('backlogItemId')).toBe(ITEM_ID);
     });
 
-    it('should return a run with its steps from two routes', async () => {
+    it('should return a run with its steps in full from two routes when asked', async () => {
       const { client } = await bootMcpPair({
         capabilities: ['products:read'],
         routes: {
@@ -1067,7 +1082,7 @@ describe('MCP server integration', () => {
         },
       });
 
-      const result = await client.callTool({ name: 'taiga_get_build', arguments: { buildId: BUILD_ID } });
+      const result = await client.callTool({ name: 'taiga_get_build', arguments: { buildId: BUILD_ID, full: true } });
 
       expect(result.isError).toBeFalsy();
       expect(parseToolResult(result)).toEqual({ ...run, steps: [step] });
@@ -1086,7 +1101,7 @@ describe('MCP server integration', () => {
       });
 
       const build = parseToolResult(
-        await client.callTool({ name: 'taiga_get_build', arguments: { buildId: BUILD_ID } })
+        await client.callTool({ name: 'taiga_get_build', arguments: { buildId: BUILD_ID, full: true } })
       );
       expect(build).toEqual({ ...run, steps: [{ ...step, verification: { ok: true } }] });
       expect(JSON.stringify(build)).not.toContain('tenantId');
@@ -1975,6 +1990,38 @@ describe('MCP server integration', () => {
       // Ten pages per open status, two statuses.
       expect(bundle.backlog.items).toHaveLength(20);
       expect(bundle.backlog.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');
+    });
+
+    it('should carry the newest fifty open items across both statuses and say the backlog is truncated', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES, routes: allRoutes });
+      const router = fetchSpy.getMockImplementation() as (url: string, init: RequestInit) => Promise<unknown>;
+      fetchSpy.mockImplementation(async (url: string, init: RequestInit) => {
+        const parsed = new URL(url);
+        if (!parsed.pathname.endsWith('/backlog')) return router(url, init);
+        // The newest initiative is still in the backlog; sixty older ones are in progress. The
+        // statuses are read one after the other, so arrival order is not age.
+        const rows =
+          parsed.searchParams.get('status') === 'in_progress'
+            ? Array.from({ length: 60 }, (_, n) => ({
+                ...item,
+                id: `0199a1b2-c3d4-7e5f-8a9b-${String(n).padStart(12, '0')}`,
+                title: `Item ${n}`,
+              }))
+            : [{ ...item, id: '0199a1b2-c3d4-7e5f-8a9c-000000000000', title: 'Newest', status: 'backlog' }];
+        const body = { data: rows, nextCursor: null };
+        return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+      });
+
+      const bundle = parseToolResult(
+        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);
     });
 
     it('should carry the two documents as section ids only when asked for a small bundle', async () => {
@@ -2712,6 +2759,7 @@ describe('MCP server integration', () => {
         'taiga_reject_plan',
         'taiga_stop_build',
         'taiga_resume_build',
+        'taiga_set_auto_build',
       ]) {
         expect(byName[name], name).toMatchObject({ readOnlyHint: false, destructiveHint: true, idempotentHint: false });
       }
@@ -2774,7 +2822,8 @@ describe('MCP server integration', () => {
       const result = await client.callTool({ name: 'taiga_queue_backlog_item', arguments: { itemId: ITEM_ID } });
 
       expect(result.isError).toBeFalsy();
-      // One write, no read around it: the route answers with the item.
+      // One write to the item, no item read around it: the route answers with the item (the reads
+      // after it are the product's gate and its queue).
       expect(fetchSpy.mock.calls.filter((c: unknown[]) => (c[0] as string).includes('/backlog/'))).toHaveLength(1);
       expect(sentBody(fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'queue' });
       expect(outcomeOf(result)).toMatchObject({ id: ITEM_ID, state: 'queue', status: 'in_progress' });
@@ -2827,9 +2876,12 @@ describe('MCP server integration', () => {
         'taiga_create_backlog_item',
         'taiga_move_backlog_item',
       ]);
-      // The resume takes an item ID a create or a queue hands back, so it needs no backlog read;
-      // the verdicts take a plan ID only the plan read gives.
-      expect(toolNames((await operatorOnly.client.listTools()).tools)).toEqual(['taiga_resume_backlog_item']);
+      // The resume and the review gate take an item ID a create or a queue hands back, so they need no
+      // backlog read; the verdicts take a plan ID only the plan read gives.
+      expect(toolNames((await operatorOnly.client.listTools()).tools)).toEqual([
+        'taiga_resume_backlog_item',
+        'taiga_set_auto_build',
+      ]);
     });
 
     it('should move an initiative into plan with a full key, and refuse queue or plan for a key without products:write before any request', async () => {
@@ -3338,6 +3390,1072 @@ describe('MCP server integration', () => {
     });
   });
 
+  describe('observing and waiting on the line', () => {
+    const QUEUED_ITEM = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a61';
+    const HEAD_ITEM = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a62';
+    const criteria = [
+      { criterion: 'AC-1 logs in', met: true },
+      { criterion: 'AC-2 logs out', met: false },
+    ];
+    const item = {
+      id: ITEM_ID,
+      productId: PRODUCT_ID,
+      title: 'Add login',
+      description: 'A long brief',
+      status: 'in_progress',
+      state: 'queue',
+      planningStatus: 'unplanned',
+      needsHumanCause: null,
+      needsHumanDetail: null,
+      autoBuild: null,
+      acceptanceCriteria: criteria,
+      lifecycle: { turn: 'idle', stage: 'backlog', cta: 'start_plan', latestBuild: null },
+    };
+    const head = {
+      ...item,
+      id: HEAD_ITEM,
+      title: 'ARC-3.3 OpenAPI',
+      state: 'build',
+      planningStatus: 'planned',
+      lifecycle: {
+        turn: 'you',
+        stage: 'in_review',
+        cta: 'review_pr',
+        latestBuild: { id: BUILD_ID, status: 'needs_review', prUrl: 'https://github.com/acme/web/pull/22' },
+      },
+    };
+    const entry = (backlogItemId: string, state: string, extra: Record<string, unknown> = {}) => ({
+      id: `e-${backlogItemId.slice(-2)}`,
+      productId: PRODUCT_ID,
+      backlogItemId,
+      position: 'a0',
+      state,
+      queuedBy: null,
+      haltReason: null,
+      haltCause: null,
+      haltParams: null,
+      queuedAt: '2026-10-08T00:00:00.000Z',
+      startedAt: null,
+      settledAt: null,
+      ...extra,
+    });
+    /** What fetch answers, for a route given as a function. */
+    const answer = (body: unknown) => ({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(body),
+      text: () => Promise.resolve(JSON.stringify(body)),
+    });
+    /** A route that answers each row in turn, then keeps answering the last. */
+    const sequence = (...rows: unknown[]) => {
+      let index = 0;
+      return () => answer({ data: rows[Math.min(index++, rows.length - 1)] });
+    };
+
+    it('should count met acceptance criteria on every list row, and say null before an item has any', async () => {
+      const unplanned = { ...item, id: QUEUED_ITEM, acceptanceCriteria: null };
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/products/${PRODUCT_ID}/backlog`]: { data: [item, unplanned], nextCursor: null } },
+      });
+
+      const rows = parseToolResult(
+        await client.callTool({ name: 'taiga_list_backlog_items', arguments: { productId: PRODUCT_ID } })
+      ).data;
+
+      expect(rows[0].criteria).toEqual({ met: 1, total: 2 });
+      expect(rows[1].criteria).toBeNull();
+      expect(rows[0]).not.toHaveProperty('acceptanceCriteria');
+    });
+
+    it('should summarize a run by default: each step without its instructions, with the headline of its report', async () => {
+      const longHeadline = 'x'.repeat(700);
+      const steps = [
+        {
+          id: 's1',
+          stepOrder: 1,
+          title: 'Add the route',
+          status: 'completed',
+          description: 'Planner instructions the summary must not carry',
+          summary: 'Added the route; tests pass.\n\nDetail the summary must not carry.',
+          commitSha: 'abc',
+          filesChanged: ['src/a.ts'],
+          verification: [{ check: 'tests', status: 'passed' }],
+          executionMetrics: { build_ms: 1 },
+          writes: ['src/a.ts'],
+        },
+        { id: 's2', stepOrder: 2, title: 'Verify', status: 'in_progress', summary: longHeadline },
+        { id: 's3', stepOrder: 3, title: 'Not yet', status: 'planned', summary: null },
+      ];
+      const run = { id: BUILD_ID, status: 'implementing', prUrl: null, completedSteps: 1, totalSteps: 3 };
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [`/v1/builds/${BUILD_ID}`]: { data: run }, [`/v1/builds/${BUILD_ID}/steps`]: { data: steps } },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_get_build', arguments: { buildId: BUILD_ID } })
+      );
+
+      expect(result).toMatchObject(run);
+      expect(result.steps[0]).toEqual({
+        stepOrder: 1,
+        title: 'Add the route',
+        status: 'completed',
+        commitSha: 'abc',
+        filesChanged: ['src/a.ts'],
+        verification: [{ check: 'tests', status: 'passed' }],
+        headline: 'Added the route; tests pass.',
+      });
+      expect(result.steps[1].headline).toBe(`${'x'.repeat(600)}...`);
+      expect(result.steps[2].headline).toBeNull();
+    });
+
+    it('should read the queue in order, name each entry and say what a halted head is waiting for', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read', 'backlog:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/queue`]: {
+            data: [
+              entry(ITEM_ID, 'settled'),
+              entry(HEAD_ITEM, 'halted', { haltCause: 'awaiting_plan_review', haltParams: {} }),
+              entry(QUEUED_ITEM, 'queued'),
+            ],
+          },
+          [`/v1/backlog/${HEAD_ITEM}`]: {
+            data: { ...head, state: 'plan', lifecycle: { ...head.lifecycle, latestBuild: null } },
+          },
+          [`/v1/backlog/${QUEUED_ITEM}`]: { data: { ...item, id: QUEUED_ITEM, title: 'README' } },
+        },
+      });
+
+      const queue = parseToolResult(
+        await client.callTool({ name: 'taiga_get_queue', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(queue.entries.map((row: { title: string }) => row.title)).toEqual(['ARC-3.3 OpenAPI', 'README']);
+      expect(queue.entries[0]).toMatchObject({
+        position: 1,
+        entryState: 'halted',
+        criteria: { met: 1, total: 2 },
+        halt: {
+          cause: 'awaiting_plan_review',
+          reason: 'The plan is ready and waiting for you to read it, so the queue stopped here.',
+          nextStep: expect.stringContaining('taiga_approve_plan'),
+        },
+      });
+      expect(queue.entries[1]).toMatchObject({ position: 2, entryState: 'queued' });
+      expect(queue.waitingOn).toMatch(
+        /^"ARC-3.3 OpenAPI" halted the queue, holding the entries behind it: The plan is ready/
+      );
+      expect(queue).not.toHaveProperty('note');
+    });
+
+    it('should say an active head waits on a person to review its pull request, which holds the line', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read', 'backlog:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/queue`]: { data: [entry(HEAD_ITEM, 'active'), entry(QUEUED_ITEM, 'queued')] },
+          [`/v1/backlog/${HEAD_ITEM}`]: { data: head },
+          [`/v1/backlog/${QUEUED_ITEM}`]: { data: { ...item, id: QUEUED_ITEM } },
+        },
+      });
+
+      const queue = parseToolResult(
+        await client.callTool({ name: 'taiga_get_queue', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(queue.entries[0]).toMatchObject({ buildId: BUILD_ID, prUrl: 'https://github.com/acme/web/pull/22' });
+      expect(queue.waitingOn).toBe(
+        '"ARC-3.3 OpenAPI" is waiting on a person (review_pr) (https://github.com/acme/web/pull/22); every other queued initiative waits until its pull request merges.'
+      );
+    });
+
+    it('should answer what the line waits on by the active entry wherever it sits, before a halted one ahead of it', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/queue`]: {
+            data: [
+              entry(QUEUED_ITEM, 'halted', { haltCause: 'run_failed', haltParams: {} }),
+              entry(HEAD_ITEM, 'active'),
+            ],
+          },
+          [`/v1/backlog/${QUEUED_ITEM}`]: { data: { ...item, id: QUEUED_ITEM, title: 'Halted one' } },
+          [`/v1/backlog/${HEAD_ITEM}`]: { data: head },
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: item },
+          [`GET /v1/products/${PRODUCT_ID}`]: { data: { id: PRODUCT_ID } },
+        },
+      });
+
+      const queue = parseToolResult(
+        await client.callTool({ name: 'taiga_get_queue', arguments: { productId: PRODUCT_ID } })
+      );
+      expect(queue.waitingOn).toMatch(/^"ARC-3.3 OpenAPI" is waiting on a person/);
+
+      fetchSpy.mockClear();
+      const queued = await client.callTool({ name: 'taiga_queue_backlog_item', arguments: { itemId: ITEM_ID } });
+      expect(queued.isError).toBeFalsy();
+      // Placing an item names only the entry the line waits on: the active one.
+      const itemReads = fetchSpy.mock.calls
+        .filter((c: unknown[]) => (c[1] as RequestInit)?.method === 'GET' && (c[0] as string).includes('/backlog/'))
+        .map((c: unknown[]) => new URL(c[0] as string).pathname);
+      expect(itemReads).toEqual([`/v1/backlog/${HEAD_ITEM}`]);
+    });
+
+    it('should say a halted entry behind others does not hold the ones ahead of it', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/queue`]: {
+            data: [
+              entry(QUEUED_ITEM, 'queued'),
+              entry(HEAD_ITEM, 'halted', { haltCause: 'run_failed', haltParams: {} }),
+            ],
+          },
+        },
+      });
+
+      const queue = parseToolResult(
+        await client.callTool({ name: 'taiga_get_queue', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(queue.waitingOn).toContain('holding the entries behind it');
+      expect(queue.waitingOn).toContain('Entries ahead of it are not held by it.');
+    });
+
+    it('should say an active entry with a landed plan waits for the Build slot, not for a person', async () => {
+      const landed = {
+        ...head,
+        state: 'plan',
+        lifecycle: { turn: 'you', stage: 'planned', cta: 'start_build', latestBuild: null },
+      };
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read', 'backlog:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/queue`]: { data: [entry(HEAD_ITEM, 'active')] },
+          [`/v1/backlog/${HEAD_ITEM}`]: { data: landed },
+        },
+      });
+
+      const queue = parseToolResult(
+        await client.callTool({ name: 'taiga_get_queue', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(queue.waitingOn).toBe(
+        '"ARC-3.3 OpenAPI" has its plan and waits for the Build slot; every other queued initiative waits until its pull request merges.'
+      );
+    });
+
+    it('should keep the queue when an entry cannot be named, and say why entries carry ids only', async () => {
+      const queueRoute = { [`/v1/products/${PRODUCT_ID}/queue`]: { data: [entry(HEAD_ITEM, 'active')] } };
+      // One pair at a time: each boot stubs the global fetch the previous client reads through.
+      const noBacklog = await bootMcpPair({ capabilities: ['products:read'], routes: queueRoute });
+      const without = parseToolResult(
+        await noBacklog.client.callTool({ name: 'taiga_get_queue', arguments: { productId: PRODUCT_ID } })
+      );
+      expect(noBacklog.fetchSpy.mock.calls.some((c: unknown[]) => (c[0] as string).includes('/backlog/'))).toBe(false);
+      const failing = await bootMcpPair({
+        capabilities: ['products:read', 'backlog:read'],
+        routes: { ...queueRoute, [`/v1/backlog/${HEAD_ITEM}`]: refusal(500, 'INTERNAL', 'boom') },
+      });
+      const failed = parseToolResult(
+        await failing.client.callTool({ name: 'taiga_get_queue', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(without.entries[0]).toEqual({ position: 1, backlogItemId: HEAD_ITEM, entryState: 'active' });
+      expect(without.note).toContain('backlog:read');
+      expect(failed.entries[0]).not.toHaveProperty('title');
+      expect(failed.note).toContain('could not be read');
+      expect(failed.waitingOn).toMatch(/^Initiative .* is the active entry/);
+    });
+
+    it('should set the review gate before the move when queueing, then report the gate and the place in line', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`PUT /v1/backlog/${ITEM_ID}/auto-build`]: { data: { ...item, autoBuild: false } },
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: { ...item, autoBuild: false } },
+          [`GET /v1/products/${PRODUCT_ID}`]: { data: { id: PRODUCT_ID, autoBuild: true } },
+          [`/v1/products/${PRODUCT_ID}/queue`]: { data: [entry(HEAD_ITEM, 'active'), entry(ITEM_ID, 'queued')] },
+          [`/v1/backlog/${HEAD_ITEM}`]: { data: head },
+        },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_queue_backlog_item', arguments: { itemId: ITEM_ID, autoBuild: false } })
+      );
+
+      // To place one item and say what the line waits on, only the blocking entry is read.
+      const itemReads = fetchSpy.mock.calls.filter(
+        (c: unknown[]) => (c[1] as RequestInit)?.method === 'GET' && (c[0] as string).includes('/backlog/')
+      );
+      expect(itemReads.map((c: unknown[]) => new URL(c[0] as string).pathname)).toEqual([`/v1/backlog/${HEAD_ITEM}`]);
+
+      const writes = fetchSpy.mock.calls
+        .filter((c: unknown[]) => (c[1] as RequestInit)?.method === 'PUT')
+        .map((c: unknown[]) => new URL(c[0] as string).pathname);
+      expect(writes).toEqual([`/v1/backlog/${ITEM_ID}/auto-build`, `/v1/backlog/${ITEM_ID}/state`]);
+      expect(sentBody(fetchSpy, 'PUT', '/auto-build')).toEqual({ autoBuild: false });
+      expect(sentBody(fetchSpy, 'PUT', '/state')).toEqual({ state: 'queue' });
+      expect(result).toMatchObject({
+        id: ITEM_ID,
+        autoBuild: false,
+        criteria: { met: 1, total: 2 },
+        reviewGate: { buildsWithoutReview: false, decidedBy: 'initiative' },
+        queue: { position: 2, of: 2, waitingOn: expect.stringContaining('ARC-3.3 OpenAPI') },
+      });
+      expect(result).not.toHaveProperty('note');
+    });
+
+    it("should leave the gate alone when queueing without autoBuild, and report the product's default as deciding", async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: item },
+          // A product row written before the field shipped: absent reads as true.
+          [`GET /v1/products/${PRODUCT_ID}`]: { data: { id: PRODUCT_ID } },
+        },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_queue_backlog_item', arguments: { itemId: ITEM_ID } })
+      );
+
+      expect(fetchSpy.mock.calls.some((c: unknown[]) => (c[0] as string).includes('/auto-build'))).toBe(false);
+      expect(result.reviewGate).toMatchObject({ buildsWithoutReview: true, decidedBy: 'product' });
+      // The queue read missed (no route); the outcome says so rather than failing the write it reports.
+      expect(result.queue).toBeNull();
+      expect(result.note).toContain('taiga_get_queue');
+    });
+
+    it('should set an initiative back to the product default with null and report the gate that now applies', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write'],
+        routes: {
+          [`PUT /v1/backlog/${ITEM_ID}/auto-build`]: { data: item },
+          [`GET /v1/products/${PRODUCT_ID}`]: { data: { id: PRODUCT_ID, autoBuild: false } },
+        },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_set_auto_build', arguments: { itemId: ITEM_ID, autoBuild: null } })
+      );
+
+      expect(sentBody(fetchSpy, 'PUT', '/auto-build')).toEqual({ autoBuild: null });
+      expect(result.reviewGate).toMatchObject({ buildsWithoutReview: false, decidedBy: 'product' });
+    });
+
+    it('should wait until the plan lands and report the item as it is then', async () => {
+      const planning = { ...item, state: 'plan', planningStatus: 'planning' };
+      const planned = {
+        ...item,
+        state: 'plan',
+        planningStatus: 'planned',
+        lifecycle: { turn: 'you', stage: 'planned', cta: 'start_build', latestBuild: null },
+      };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: sequence(planning, planning, planned) },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'planned', timeoutSeconds: 30 },
+        })
+      );
+
+      expect(result).toMatchObject({
+        until: 'planned',
+        reached: true,
+        item: {
+          planningStatus: 'planned',
+          lifecycle: { turn: 'you', stage: 'planned' },
+          criteria: { met: 1, total: 2 },
+        },
+      });
+      expect(fetchSpy.mock.calls.filter((c: unknown[]) => (c[0] as string).includes('/backlog/'))).toHaveLength(3);
+    });
+
+    it('should stop waiting as soon as the initiative needs a person, since the condition cannot come true on its own', async () => {
+      const flagged = { ...item, needsHumanCause: 'planning_failed', planningStatus: 'failed' };
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: sequence(item, flagged) },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_wait_for_backlog_item', arguments: { itemId: ITEM_ID, until: 'pr_open' } })
+      );
+
+      expect(result).toMatchObject({ reached: false, stoppedBecause: 'needs a person: planning_failed' });
+    });
+
+    it('should stop waiting at an ordinary gate that sets no flag: a plan waiting for its verdict, a pull request for its review', async () => {
+      const awaitingVerdict = {
+        ...item,
+        state: 'plan',
+        planningStatus: 'planned',
+        lifecycle: { turn: 'you', stage: 'planned', cta: 'start_build', latestBuild: null },
+      };
+      // The initiative's own closed gate: no product read needed.
+      const verdict = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: { data: { ...awaitingVerdict, autoBuild: false } } },
+      });
+      const plan = parseToolResult(
+        await verdict.client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'pr_open' },
+        })
+      );
+      expect(plan).toMatchObject({ reached: false, stoppedBecause: 'waits on a person: start_build' });
+
+      // No gate of its own and a key that cannot read the product's default: unknown, said as such.
+      const unknown = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: { data: awaitingVerdict } },
+      });
+      const unsure = parseToolResult(
+        await unknown.client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'your_turn' },
+        })
+      );
+      expect(unsure.reached).toBe(false);
+      expect(unsure.stoppedBecause).toMatch(/whether it waits for a review is unknown/);
+
+      const review = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: { data: head } },
+      });
+      const pr = parseToolResult(
+        await review.client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'done' },
+        })
+      );
+      expect(pr).toMatchObject({ reached: false, stoppedBecause: 'waits on a person: review_pr' });
+    });
+
+    it('should not let a slow read outlast the timeout: the read is cut at the deadline', async () => {
+      let call = 0;
+      let hung: AbortSignal | undefined;
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: {
+          [`/v1/backlog/${ITEM_ID}`]: (_url: string, init: RequestInit) => {
+            if (call++ === 0) return answer({ data: item });
+            hung = init.signal!;
+            // An API that never answers: only the abort ends this read.
+            return new Promise((_resolve, reject) =>
+              init.signal!.addEventListener('abort', () => reject(init.signal!.reason))
+            );
+          },
+        },
+      });
+
+      const started = Date.now();
+      const result = parseToolResult(
+        await client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'planned', timeoutSeconds: 1 },
+        })
+      );
+
+      expect(Date.now() - started).toBeLessThan(1_500);
+      expect(result).toMatchObject({ reached: false, stoppedBecause: 'timeout', item: { id: ITEM_ID } });
+      expect(hung?.aborted).toBe(true);
+    });
+
+    it('should answer a timeout, with no item, when not even the first read comes back in time', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: {
+          [`/v1/backlog/${ITEM_ID}`]: (_url: string, init: RequestInit) =>
+            new Promise((_resolve, reject) =>
+              init.signal!.addEventListener('abort', () => reject(init.signal!.reason))
+            ),
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_wait_for_backlog_item',
+        arguments: { itemId: ITEM_ID, until: 'planned', timeoutSeconds: 1 },
+      });
+
+      expect(result.isError).toBeFalsy();
+      expect(parseToolResult(result)).toMatchObject({ reached: false, stoppedBecause: 'timeout', item: null });
+    });
+
+    it('should wake a wait for any change when the pull request closes and nothing else moves', async () => {
+      const run = {
+        id: BUILD_ID,
+        status: 'implementing',
+        completedSteps: 2,
+        prUrl: 'https://github.com/acme/web/pull/9',
+        prMerged: false,
+      };
+      const withRun = (prState: string) => ({
+        ...item,
+        lifecycle: { turn: 'agent', stage: 'building', cta: null, latestBuild: { ...run, prState } },
+      });
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: sequence(withRun('open'), withRun('open'), withRun('closed')) },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_wait_for_backlog_item', arguments: { itemId: ITEM_ID, until: 'changed' } })
+      );
+
+      expect(result).toMatchObject({ reached: true, item: { latestBuild: { prState: 'closed' } } });
+    });
+
+    it('should end the read in flight when the call is cancelled', async () => {
+      let call = 0;
+      let hung: AbortSignal | undefined;
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: {
+          [`/v1/backlog/${ITEM_ID}`]: (_url: string, init: RequestInit) => {
+            if (call++ === 0) return answer({ data: item });
+            hung = init.signal!;
+            return new Promise((_resolve, reject) =>
+              init.signal!.addEventListener('abort', () => reject(init.signal!.reason))
+            );
+          },
+        },
+      });
+      const controller = new AbortController();
+
+      const pending = client.callTool(
+        { name: 'taiga_wait_for_backlog_item', arguments: { itemId: ITEM_ID, until: 'planned', timeoutSeconds: 60 } },
+        undefined,
+        { signal: controller.signal }
+      );
+      await vi.waitFor(() => expect(hung).toBeDefined());
+      controller.abort();
+
+      await expect(pending).rejects.toThrow();
+      await vi.waitFor(() => expect(hung!.aborted).toBe(true));
+    });
+
+    it('should not count a merged pull request as open, nor a canceled initiative as done', async () => {
+      const merged = {
+        ...item,
+        state: 'done',
+        lifecycle: {
+          turn: 'idle',
+          stage: 'done',
+          cta: null,
+          latestBuild: {
+            id: BUILD_ID,
+            status: 'completed',
+            prUrl: 'https://github.com/acme/web/pull/24',
+            prState: 'closed',
+            prMerged: true,
+          },
+        },
+      };
+      const shipped = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: { data: merged } },
+      });
+      const pr = parseToolResult(
+        await shipped.client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'pr_open' },
+        })
+      );
+      expect(pr).toMatchObject({ reached: false, stoppedBecause: 'the initiative is done' });
+
+      const canceled = {
+        ...item,
+        state: 'canceled',
+        lifecycle: { turn: 'idle', stage: 'canceled', cta: null, latestBuild: null },
+      };
+      const dropped = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: { data: canceled } },
+      });
+      const done = parseToolResult(
+        await dropped.client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'done' },
+        })
+      );
+      expect(done).toMatchObject({ reached: false, stoppedBecause: 'the initiative is canceled' });
+
+      const run = {
+        id: BUILD_ID,
+        status: 'completed',
+        completedSteps: 3,
+        prUrl: 'https://github.com/acme/web/pull/24',
+        prState: 'closed',
+        prMerged: true,
+      };
+      const finished = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [`/v1/builds/${BUILD_ID}`]: { data: run } },
+      });
+      const runPr = parseToolResult(
+        await finished.client.callTool({
+          name: 'taiga_wait_for_build',
+          arguments: { buildId: BUILD_ID, until: 'pr_open' },
+        })
+      );
+      expect(runPr).toMatchObject({ reached: false, stoppedBecause: 'the run is completed' });
+    });
+
+    it("should not take a landed plan behind an open review gate for a person's turn: it waits for the Build slot", async () => {
+      const landed = {
+        ...item,
+        state: 'plan',
+        planningStatus: 'planned',
+        autoBuild: true,
+        lifecycle: { turn: 'you', stage: 'planned', cta: 'start_build', latestBuild: null },
+      };
+      const building = {
+        ...landed,
+        state: 'build',
+        lifecycle: {
+          turn: 'agent',
+          stage: 'building',
+          cta: null,
+          latestBuild: {
+            id: BUILD_ID,
+            status: 'implementing',
+            prUrl: 'https://github.com/acme/web/pull/9',
+            prState: 'open',
+          },
+        },
+      };
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: sequence(landed, landed, building) },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_wait_for_backlog_item', arguments: { itemId: ITEM_ID, until: 'pr_open' } })
+      );
+
+      // Not stopped at the landed plan: the open gate builds it without anyone.
+      expect(result).toMatchObject({ reached: true, item: { latestBuild: { 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 () => {
+      const landed = {
+        ...item,
+        state: 'plan',
+        planningStatus: 'planned',
+        autoBuild: null,
+        lifecycle: { turn: 'you', stage: 'planned', cta: 'start_build', latestBuild: null },
+      };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['backlog:read', 'products:read'],
+        routes: {
+          [`/v1/backlog/${ITEM_ID}`]: sequence(
+            { ...landed, planningStatus: 'planning', lifecycle: item.lifecycle },
+            landed
+          ),
+          [`GET /v1/products/${PRODUCT_ID}`]: { data: { id: PRODUCT_ID, autoBuild: false } },
+        },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'your_turn' },
+        })
+      );
+
+      expect(result).toMatchObject({ reached: true, item: { lifecycle: { cta: 'start_build' } } });
+      const productReads = fetchSpy.mock.calls.filter(
+        (c: unknown[]) => new URL(c[0] as string).pathname === `/v1/products/${PRODUCT_ID}`
+      );
+      expect(productReads).toHaveLength(1);
+    });
+
+    it('should ride out a transient failure of the first read, and of the product read behind the gate', async () => {
+      const failing = { ok: false, status: 503, json: async () => ({}), text: async () => '{"message":"Unavailable"}' };
+      const landed = {
+        ...item,
+        state: 'plan',
+        planningStatus: 'planned',
+        autoBuild: null,
+        lifecycle: { turn: 'you', stage: 'planned', cta: 'start_build', latestBuild: null },
+      };
+      let itemCalls = 0;
+      let productCalls = 0;
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read', 'products:read'],
+        routes: {
+          [`/v1/backlog/${ITEM_ID}`]: () => (itemCalls++ === 0 ? failing : answer({ data: landed })),
+          [`GET /v1/products/${PRODUCT_ID}`]: () =>
+            productCalls++ === 0 ? failing : answer({ data: { id: PRODUCT_ID, autoBuild: false } }),
+        },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'your_turn' },
+        })
+      );
+
+      // A 503 on the first item read, then a 503 on the product read: both retried, then the closed gate answers.
+      expect(result).toMatchObject({ reached: true, item: { lifecycle: { cta: 'start_build' } } });
+      expect(productCalls).toBe(2);
+    });
+
+    it('should answer reached: false at the timeout', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: { data: item } },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'changed', timeoutSeconds: 1 },
+        })
+      );
+
+      expect(result).toMatchObject({ until: 'changed', reached: false, stoppedBecause: 'timeout', waitedSeconds: 1 });
+    });
+
+    it('should report progress while waiting when the client asks for it', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: {
+          [`/v1/backlog/${ITEM_ID}`]: sequence(item, item, { ...item, state: 'plan', planningStatus: 'planning' }),
+        },
+      });
+      const onprogress = vi.fn();
+
+      const result = await client.callTool(
+        { name: 'taiga_wait_for_backlog_item', arguments: { itemId: ITEM_ID, until: 'changed' } },
+        undefined,
+        { onprogress }
+      );
+
+      expect(parseToolResult(result).reached).toBe(true);
+      expect(onprogress).toHaveBeenCalledWith(expect.objectContaining({ message: 'Still waiting' }));
+    });
+
+    it('should wait for a run to finish a step, and stop early when it settles without a pull request', async () => {
+      const running = { id: BUILD_ID, status: 'implementing', completedSteps: 1, prUrl: null, error: 'noise' };
+      // One pair at a time: each boot stubs the global fetch the previous client reads through.
+      const stepped = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [`/v1/builds/${BUILD_ID}`]: sequence(running, { ...running, completedSteps: 2 }) },
+      });
+      const step = parseToolResult(
+        await stepped.client.callTool({
+          name: 'taiga_wait_for_build',
+          arguments: { buildId: BUILD_ID, until: 'step_done' },
+        })
+      );
+      const failed = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [`/v1/builds/${BUILD_ID}`]: sequence(running, { ...running, status: 'failed' }) },
+      });
+      const settled = parseToolResult(
+        await failed.client.callTool({
+          name: 'taiga_wait_for_build',
+          arguments: { buildId: BUILD_ID, until: 'pr_open' },
+        })
+      );
+
+      expect(step).toMatchObject({ reached: true, run: { completedSteps: 2 } });
+      expect(step.run).not.toHaveProperty('error');
+      expect(settled).toMatchObject({ reached: false, stoppedBecause: 'the run is failed', run: { status: 'failed' } });
+    });
+
+    it('should ride out a transient read failure while waiting, and give up after three in a row', async () => {
+      const failing = { ok: false, status: 502, json: async () => ({}), text: async () => '{"message":"Bad gateway"}' };
+      const reads = [answer({ data: item }), failing, answer({ data: { ...item, planningStatus: 'planned' } })];
+      let call = 0;
+      const recovered = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: () => reads[Math.min(call++, reads.length - 1)] },
+      });
+      const result = parseToolResult(
+        await recovered.client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'planned' },
+        })
+      );
+      expect(result.reached).toBe(true);
+
+      let calls = 0;
+      const broken = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: () => (calls++ === 0 ? answer({ data: item }) : failing) },
+      });
+      const failed = await broken.client.callTool({
+        name: 'taiga_wait_for_backlog_item',
+        arguments: { itemId: ITEM_ID, until: 'planned' },
+      });
+      expect(failed.isError).toBe(true);
+      expect(calls).toBe(4);
+    });
+
+    it('should stop a wait for the plan when planning fails, and keep waiting on a flagged item when asked for any change', async () => {
+      const failedPlan = { ...item, planningStatus: 'failed' };
+      const planning = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: sequence(item, failedPlan) },
+      });
+      const stopped = parseToolResult(
+        await planning.client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'planned' },
+        })
+      );
+      expect(stopped).toMatchObject({ reached: false, stoppedBecause: 'planning failed' });
+
+      const flagged = { ...item, needsHumanCause: 'planning_failed' };
+      const waiting = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: sequence(flagged, flagged, { ...item, state: 'plan' }) },
+      });
+      const changed = parseToolResult(
+        await waiting.client.callTool({
+          name: 'taiga_wait_for_backlog_item',
+          arguments: { itemId: ITEM_ID, until: 'changed' },
+        })
+      );
+      expect(changed).toMatchObject({ reached: true, item: { state: 'plan', needsHumanCause: null } });
+    });
+
+    it('should not move the initiative when setting its gate is refused', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`PUT /v1/backlog/${ITEM_ID}/auto-build`]: refusal(409, 'CONFLICT', 'This initiative is finished.'),
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: item },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_queue_backlog_item',
+        arguments: { itemId: ITEM_ID, autoBuild: false },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toEqual({ error: 'CONFLICT', message: 'This initiative is finished.' });
+      expect(fetchSpy.mock.calls.some((c: unknown[]) => (c[0] as string).includes('/state'))).toBe(false);
+    });
+
+    it('should say the gate could not be read when the key cannot read the product', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:write'],
+        routes: {
+          [`PUT /v1/backlog/${ITEM_ID}/auto-build`]: { data: item },
+          [`GET /v1/products/${PRODUCT_ID}`]: refusal(403, 'FORBIDDEN', 'No'),
+        },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_set_auto_build', arguments: { itemId: ITEM_ID, autoBuild: null } })
+      );
+
+      expect(result.reviewGate).toBeNull();
+      expect(result.note).toContain('taiga_get_product');
+    });
+
+    it("should report an initiative's own gate without reading the product, which it does not need", async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:write'],
+        routes: { [`PUT /v1/backlog/${ITEM_ID}/auto-build`]: { data: { ...item, autoBuild: false } } },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_set_auto_build', arguments: { itemId: ITEM_ID, autoBuild: false } })
+      );
+
+      expect(result.reviewGate).toMatchObject({ buildsWithoutReview: false, decidedBy: 'initiative' });
+      expect(result).not.toHaveProperty('note');
+      expect(
+        fetchSpy.mock.calls.some((c: unknown[]) => new URL(c[0] as string).pathname === `/v1/products/${PRODUCT_ID}`)
+      ).toBe(false);
+    });
+
+    it('should advise each halt from the registry: resume where a person may, wait where it clears itself', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/queue`]: {
+            data: [
+              entry(HEAD_ITEM, 'halted', { haltCause: 'run_failed', haltParams: {} }),
+              entry(QUEUED_ITEM, 'halted', { haltCause: 'activation_refused', haltParams: { message: 'No seats' } }),
+              entry(ITEM_ID, 'halted', { haltCause: 'not_a_cause_yet', haltReason: 'Stored prose' }),
+            ],
+          },
+        },
+      });
+
+      const [failed, refused, unknown] = parseToolResult(
+        await client.callTool({ name: 'taiga_get_queue', arguments: { productId: PRODUCT_ID } })
+      ).entries;
+
+      expect(failed.halt.nextStep).toMatch(/^It clears when the run is retried/);
+      expect(refused.halt).toMatchObject({
+        reason: 'No seats',
+        nextStep: expect.stringMatching(/^taiga_resume_backlog_item lifts it/),
+      });
+      expect(unknown.halt).toMatchObject({
+        reason: 'Stored prose',
+        nextStep: expect.stringContaining('taiga_get_backlog_item'),
+      });
+    });
+
+    it('should fail the queue read on a fault that is not the API, rather than hide it as an unnamed entry', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read', 'backlog:read'],
+        routes: {
+          [`/v1/products/${PRODUCT_ID}/queue`]: { data: [entry(HEAD_ITEM, 'active')] },
+          [`/v1/backlog/${HEAD_ITEM}`]: () => {
+            throw new Error('a bug, not the API');
+          },
+        },
+      });
+
+      const result = await client.callTool({ name: 'taiga_get_queue', arguments: { productId: PRODUCT_ID } });
+
+      expect(result.isError).toBe(true);
+      expect((result.content as { text: string }[])[0]!.text).toContain('a bug, not the API');
+    });
+
+    it('should refuse an argument a tool does not take, before any request', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+      const before = fetchSpy.mock.calls.length;
+
+      const result = await client.callTool({
+        name: 'taiga_approve_plan',
+        arguments: { planId: '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a60', comment: 'Looks right' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect((result.content as { text: string }[])[0]!.text).toMatch(/Unrecognized key.*comment/s);
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+  });
+
+  describe('document budgets', () => {
+    const product = { id: PRODUCT_ID, name: 'Web', slug: 'web', factoryId: FACTORY_ID, settings: {} };
+    const section = (content: string) => ({ source: 'derived', content });
+    const bigSpec = {
+      id: 'doc-spec',
+      type: 'specification',
+      version: 4,
+      isDraft: false,
+      origin: 'plan',
+      data: {
+        sections: {
+          overview: section('o'.repeat(5_000)),
+          features: section('f'.repeat(5_000)),
+          flows: section('l'.repeat(5_000)),
+          risks: section('r'.repeat(1_000)),
+        },
+      },
+    };
+    const routes = (spec: unknown) => ({
+      [`GET /v1/products/${PRODUCT_ID}`]: { data: product },
+      [`GET /v1/products/${PRODUCT_ID}/documents/specification?origin=plan`]: { data: spec },
+    });
+
+    it('should carry the whole sections that fit the budget, skipping one that does not, name the rest and say how large it is', async () => {
+      const { client } = await bootMcpPair({ capabilities: ['products:read'], routes: routes(bigSpec) });
+
+      const raw = await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } });
+      const bundle = parseToolResult(raw);
+
+      // The size it reports is the size of the text it hands over, the field included.
+      expect(bundle.characters).toBe((raw.content as { text: string }[])[0]!.text.length);
+      const spec = bundle.documents.specification;
+      // flows would pass the budget; risks, after it, still fits.
+      expect(Object.keys(spec.data.sections)).toEqual(['overview', 'features', 'risks']);
+      expect(spec.data.sections.overview).toEqual(section('o'.repeat(5_000)));
+      expect(spec.omittedSections).toEqual([{ id: 'flows', characters: 5_000 }]);
+      expect(bundle.documents.notes).toEqual(expect.arrayContaining([expect.stringContaining('omittedSections')]));
+      expect(bundle.characters).toBeGreaterThan(10_000);
+      expect(bundle.characters).toBeLessThan(20_000);
+    });
+
+    it('should never cut a section: one past the budget alone is named, and fullDocuments carries everything', async () => {
+      // The order a jsonb column hands back: shorter ids first, whatever order they were written in.
+      const huge = {
+        ...bigSpec,
+        data: { sections: { tail: section('t'), overview: section('o'.repeat(30_000)) } },
+      };
+      const { client } = await bootMcpPair({ capabilities: ['products:read'], routes: routes(huge) });
+
+      const cut = parseToolResult(
+        await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+      ).documents.specification;
+      const full = parseToolResult(
+        await client.callTool({
+          name: 'taiga_get_product_context',
+          arguments: { productId: PRODUCT_ID, fullDocuments: true },
+        })
+      ).documents.specification;
+
+      expect(cut.data.sections).toEqual({ tail: section('t') });
+      expect(cut.omittedSections).toEqual([{ id: 'overview', characters: 30_000 }]);
+      expect(full.data.sections.overview.content).toHaveLength(30_000);
+      expect(full).not.toHaveProperty('omittedSections');
+    });
+
+    it("should leave each section's citations out of the bundle and say so, while fullDocuments keeps them", async () => {
+      const cited = {
+        ...bigSpec,
+        data: { sections: { overview: { ...section('text'), citations: [{ path: 'src/a.rs', lines: '1-9' }] } } },
+      };
+      const { client } = await bootMcpPair({ capabilities: ['products:read'], routes: routes(cited) });
+
+      const lean = parseToolResult(
+        await client.callTool({ name: 'taiga_get_product_context', arguments: { productId: PRODUCT_ID } })
+      ).documents;
+      const full = parseToolResult(
+        await client.callTool({
+          name: 'taiga_get_product_context',
+          arguments: { productId: PRODUCT_ID, fullDocuments: true },
+        })
+      ).documents;
+
+      expect(lean.specification.data.sections.overview).toEqual(section('text'));
+      expect(lean.notes).toEqual(expect.arrayContaining([expect.stringContaining('citations')]));
+      expect(full.specification.data.sections.overview.citations).toHaveLength(1);
+    });
+
+    it('should read only the named sections of a product document and list the rest', async () => {
+      const { client } = await bootMcpPair({ capabilities: ['products:read'], routes: routes(bigSpec) });
+
+      const doc = parseToolResult(
+        await client.callTool({
+          name: 'taiga_get_product_document',
+          arguments: { productId: PRODUCT_ID, type: 'specification', origin: 'plan', sections: ['risks', 'flows'] },
+        })
+      );
+      const miss = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'specification', origin: 'plan', sections: ['nope'] },
+      });
+
+      // The document's own order, whatever order they were asked in.
+      expect(Object.keys(doc.data.sections)).toEqual(['flows', 'risks']);
+      expect(doc.omittedSections.map((s: { id: string }) => s.id)).toEqual(['overview', 'features']);
+      expect(miss.isError).toBe(true);
+      expect(parseToolResult(miss).message).toBe(
+        'The plan specification has no section nope; its sections are overview, features, flows, risks.'
+      );
+    });
+  });
+
   describe('error handling', () => {
     it('should surface API errors as structured MCP error content', async () => {
       // Introspect succeeds, but all other endpoints fail