@taiga-ai/mcp-server 0.12.0-rc.419 → 0.13.0-dev.422

package/package.json

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

package/src/client.ts

@@ -297,6 +297,34 @@ export class TaigaClient {
     );
   }
 
+  /**
+   * Stop or start the product's line. Stopping halts pulls and builds and
+   * stops the plan and build in flight; starting picks the interrupted work
+   * back up.
+   */
+  async setLineStopped(productId: string, stopped: boolean) {
+    return this.request<{ data: unknown }>('PUT', `/products/${seg(productId)}/line`, { stopped });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Agent jobs
+  // ---------------------------------------------------------------------------
+
+  /** Ask an agent for work: the job is queued and runs in the background. */
+  async createAgentJob(body: {
+    scope: 'product' | 'tenant';
+    type: string;
+    targetId: string;
+    documentType?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+  }) {
+    return this.request<{ data: unknown }>('POST', '/agent-jobs', body);
+  }
+
+  async getAgentJob(id: string, signal?: AbortSignal) {
+    return this.request<{ data: unknown }>('GET', `/agent-jobs/${seg(id)}`, undefined, { signal });
+  }
+
   async getProductDocument(productId: string, type: string, origin?: string) {
     const qs = origin ? `?${new URLSearchParams({ origin })}` : '';
     return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/documents/${seg(type)}${qs}`);
@@ -340,26 +368,15 @@ export class TaigaClient {
     return this.request<{ data: unknown }>('GET', `/backlog/${seg(itemId)}`, undefined, { signal });
   }
 
-  async createBacklogItem(
-    productId: string,
-    body: {
-      title: string;
-      description: string;
-      category?: string | undefined;
-      priority?: number | undefined;
-      estimate?: number | undefined;
-    }
-  ) {
-    // The route's body schema names the product too, as the web's
-    // CreateBacklogItemInput does (the live run found it; the handler then
-    // takes the one from the path). Dropping it is an API contract change.
-    return this.request<{ data: unknown }>('POST', `/products/${seg(productId)}/backlog`, { ...body, productId });
-  }
-
   /** A person's move on the line board: the column dropped into, and what to follow there. */
   async transitionInitiative(
     itemId: string,
-    body: { state: string; afterId?: string | null | undefined; archived?: boolean | undefined }
+    body: {
+      state: string;
+      afterId?: string | null | undefined;
+      archived?: boolean | undefined;
+      force?: boolean | undefined;
+    }
   ) {
     return this.request<{ data: unknown }>('PUT', `/backlog/${seg(itemId)}/state`, body);
   }
@@ -433,10 +450,6 @@ export class TaigaClient {
     return this.request<{ data: unknown }>('POST', `/builds/${seg(id)}/stop`);
   }
 
-  async resumeBuildRun(id: string) {
-    return this.request<{ data: unknown }>('POST', `/builds/${seg(id)}/resume`);
-  }
-
   async listBuildRunSteps(id: string) {
     return this.request<{ data: unknown[] }>('GET', `/builds/${seg(id)}/steps`);
   }

package/src/server.integration.test.ts

@@ -27,11 +27,11 @@ const ALL_CAPABILITIES = [
  */
 const ALL_TOOL_NAMES = [
   'taiga_approve_plan',
-  'taiga_create_backlog_item',
   'taiga_get_backlog_item',
   'taiga_get_build',
   'taiga_get_document',
   'taiga_get_factory_document',
+  'taiga_get_job',
   'taiga_get_plan',
   'taiga_get_product',
   'taiga_get_product_context',
@@ -45,19 +45,22 @@ const ALL_TOOL_NAMES = [
   'taiga_list_product_documents',
   'taiga_list_products',
   'taiga_move_backlog_item',
+  'taiga_pause_line',
+  'taiga_plan_again',
   'taiga_publish_document',
   'taiga_publish_factory_document',
   'taiga_queue_backlog_item',
   'taiga_reject_plan',
+  'taiga_request_initiatives',
   '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',
+  'taiga_wait_for_job',
 ];
 
 const PRODUCT_ID = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c';
@@ -365,6 +368,8 @@ describe('MCP server integration', () => {
         'taiga_get_build',
         'taiga_get_queue',
         'taiga_wait_for_build',
+        'taiga_get_job',
+        'taiga_wait_for_job',
       ],
       'backlog:read': [
         'taiga_list_backlog_items',
@@ -378,11 +383,12 @@ describe('MCP server integration', () => {
     const PAIRED_CONTRACT: Record<string, string[]> = {
       'tenant:documents:read tenant:documents:write': ['taiga_update_document', 'taiga_publish_document'],
       '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': ['taiga_move_backlog_item'],
       'backlog:write products:write': ['taiga_queue_backlog_item'],
-      'products:write': ['taiga_resume_backlog_item', 'taiga_set_auto_build'],
+      'products:write': ['taiga_resume_backlog_item', 'taiga_set_auto_build', 'taiga_request_initiatives'],
       'backlog:read products:write': ['taiga_approve_plan', 'taiga_reject_plan'],
-      'products:read products:write': ['taiga_stop_build', 'taiga_resume_build'],
+      'backlog:read backlog:write products:write': ['taiga_plan_again'],
+      'products:read products:write': ['taiga_stop_build', 'taiga_pause_line'],
     };
 
     for (const [capability, expectedTools] of [...Object.entries(CONTRACT), ...Object.entries(PAIRED_CONTRACT)]) {
@@ -2745,7 +2751,7 @@ describe('MCP server integration', () => {
     };
     const outcomeOf = (result: Record<string, unknown>) => parseToolResult(result);
 
-    it('should mark every tool that starts or stops agent work destructive, and the create not', async () => {
+    it('should mark every tool that starts or stops agent work destructive, and the reads not', async () => {
       const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
 
       const { tools } = await client.listTools();
@@ -2758,59 +2764,177 @@ describe('MCP server integration', () => {
         'taiga_approve_plan',
         'taiga_reject_plan',
         'taiga_stop_build',
-        'taiga_resume_build',
-        'taiga_set_auto_build',
+        'taiga_request_initiatives',
+        'taiga_plan_again',
       ]) {
         expect(byName[name], name).toMatchObject({ readOnlyHint: false, destructiveHint: true, idempotentHint: false });
       }
-      expect(byName.taiga_create_backlog_item).toMatchObject({ readOnlyHint: false, destructiveHint: false });
-      expect(byName.taiga_get_plan).toMatchObject({ readOnlyHint: true });
+      // Settings: the same call twice leaves things as one call does.
+      for (const name of ['taiga_set_auto_build', 'taiga_pause_line']) {
+        expect(byName[name], name).toMatchObject({ readOnlyHint: false, destructiveHint: true, idempotentHint: true });
+      }
+      for (const name of ['taiga_get_plan', 'taiga_get_job', 'taiga_wait_for_job']) {
+        expect(byName[name], name).toMatchObject({ readOnlyHint: true });
+      }
     });
 
-    it('should create an initiative in the product and answer with where it stands, not the brief', async () => {
+    it('should ask an agent for initiatives the way the web does, and answer with the job', async () => {
+      const job = {
+        id: 'job-1',
+        type: 'generate_backlog',
+        status: 'pending',
+        targetId: PRODUCT_ID,
+        result: null,
+        metadata: {},
+      };
       const { client, fetchSpy } = await bootMcpPair({
         capabilities: ALL_CAPABILITIES,
-        routes: { [`POST /v1/products/${PRODUCT_ID}/backlog`]: { data: item } },
+        routes: { 'POST /v1/agent-jobs': { data: job } },
       });
 
       const result = await client.callTool({
-        name: 'taiga_create_backlog_item',
-        arguments: {
-          productId: PRODUCT_ID,
-          title: 'Add login',
-          description: 'Users log in.',
-          category: 'feature',
-          priority: 2,
-        },
+        name: 'taiga_request_initiatives',
+        arguments: { productId: PRODUCT_ID, title: '  Add login ', description: ' Users log in.  ' },
       });
 
       expect(result.isError).toBeFalsy();
-      // The route wants the product in the body as well as the path.
-      expect(sentBody(fetchSpy, 'POST', `/products/${PRODUCT_ID}/backlog`)).toEqual({
-        productId: PRODUCT_ID,
-        title: 'Add login',
-        description: 'Users log in.',
-        category: 'feature',
-        priority: 2,
+      // The body generateBacklogJob.ts builds: title and description trimmed, joined by a blank line.
+      expect(sentBody(fetchSpy, 'POST', '/agent-jobs')).toEqual({
+        scope: 'product',
+        type: 'generate_backlog',
+        targetId: PRODUCT_ID,
+        metadata: { userPrompt: 'Add login\n\nUsers log in.' },
       });
-      const outcome = outcomeOf(result);
-      expect(outcome).toMatchObject({ id: ITEM_ID, state: 'backlog', lifecycle });
-      expect(outcome).not.toHaveProperty('description');
-      expect(outcome).not.toHaveProperty('acceptanceCriteria');
+      expect(outcomeOf(result)).toEqual({
+        id: 'job-1',
+        type: 'generate_backlog',
+        targetId: PRODUCT_ID,
+        status: 'pending',
+      });
+      // Nothing writes an initiative directly: the agent does.
+      expect(fetchSpy.mock.calls.some((c: unknown[]) => (c[0] as string).endsWith('/backlog'))).toBe(false);
     });
 
-    it('should refuse a create with no title or a brief past the limit before any request', async () => {
-      const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
-      const before = fetchSpy.mock.calls.length;
+    it('should ask for a suggestion when the request is empty, sending no prompt at all', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { 'POST /v1/agent-jobs': { data: { id: 'job-2', type: 'generate_backlog', status: 'pending' } } },
+      });
 
-      for (const args of [
-        { productId: PRODUCT_ID, title: '', description: 'x' },
-        { productId: PRODUCT_ID, title: 'T', description: 'x'.repeat(20_001) },
-      ]) {
-        const result = await client.callTool({ name: 'taiga_create_backlog_item', arguments: args });
-        expect(result.isError).toBe(true);
-      }
-      expect(fetchSpy.mock.calls.length).toBe(before);
+      await client.callTool({ name: 'taiga_request_initiatives', arguments: { productId: PRODUCT_ID, title: '   ' } });
+
+      expect(sentBody(fetchSpy, 'POST', '/agent-jobs')).toEqual({
+        scope: 'product',
+        type: 'generate_backlog',
+        targetId: PRODUCT_ID,
+      });
+    });
+
+    it('should say what an initiative request came to: the initiatives it added, or why it added none', async () => {
+      const JOB_1 = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a71';
+      const JOB_2 = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a72';
+      const reason = {
+        policyCode: 'ARC',
+        quotedSpan: 'Services must not share a database.',
+        conflict: 'The request shares the orders database.',
+        alternative: 'An API between the services.',
+        overridePath: 'Record an exception with the architecture board.',
+      };
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/agent-jobs/${JOB_1}`]: {
+            data: {
+              id: JOB_1,
+              type: 'generate_backlog',
+              status: 'completed',
+              metadata: { userPrompt: 'the request' },
+              result: { createdInitiatives: [{ id: ITEM_ID, title: 'Add login' }], createdInitiativeIds: [ITEM_ID] },
+            },
+          },
+          [`/v1/agent-jobs/${JOB_2}`]: {
+            data: {
+              id: JOB_2,
+              type: 'generate_backlog',
+              status: 'completed',
+              result: {
+                outcome: 'needs_decision',
+                message: 'Your architecture policy does not allow this.',
+                coveredByPriority: null,
+                coveredById: null,
+                coveredInitiative: null,
+                reason,
+              },
+            },
+          },
+        },
+      });
+
+      const added = outcomeOf(await client.callTool({ name: 'taiga_get_job', arguments: { jobId: JOB_1 } }));
+      const refused = outcomeOf(await client.callTool({ name: 'taiga_get_job', arguments: { jobId: JOB_2 } }));
+
+      expect(added).toEqual({
+        id: JOB_1,
+        type: 'generate_backlog',
+        status: 'completed',
+        outcome: { outcome: 'created', initiatives: [{ id: ITEM_ID, title: 'Add login' }] },
+      });
+      expect(added).not.toHaveProperty('metadata');
+      expect(refused.outcome).toEqual({
+        outcome: 'needs_decision',
+        message: 'Your architecture policy does not allow this.',
+        coveredBy: null,
+        policy: reason,
+      });
+    });
+
+    it('should read an older request that recorded only the ids of what it added', async () => {
+      const JOB = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a74';
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/agent-jobs/${JOB}`]: {
+            data: {
+              id: JOB,
+              type: 'generate_backlog',
+              status: 'completed',
+              result: { createdInitiativeIds: [ITEM_ID] },
+            },
+          },
+        },
+      });
+
+      const job = outcomeOf(await client.callTool({ name: 'taiga_get_job', arguments: { jobId: JOB } }));
+
+      expect(job.outcome).toEqual({ outcome: 'created', initiatives: [{ id: ITEM_ID }] });
+    });
+
+    it('should wait for a request to finish and answer with what it came to', async () => {
+      const JOB = '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a73';
+      const running = { id: JOB, type: 'generate_backlog', status: 'processing', progress: 40, result: null };
+      const finished = {
+        ...running,
+        status: 'completed',
+        progress: 100,
+        result: { createdInitiatives: [{ id: ITEM_ID, title: 'Add login' }] },
+      };
+      let call = 0;
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [`/v1/agent-jobs/${JOB}`]: () => {
+            const body = { data: call++ < 2 ? running : finished };
+            return { ok: true, status: 200, json: async () => body, text: async () => JSON.stringify(body) };
+          },
+        },
+      });
+
+      const result = outcomeOf(await client.callTool({ name: 'taiga_wait_for_job', arguments: { jobId: JOB } }));
+
+      expect(result).toMatchObject({
+        reached: true,
+        job: { status: 'completed', outcome: { outcome: 'created', initiatives: [{ id: ITEM_ID }] } },
+      });
     });
 
     it('should queue an initiative with the move the web makes and answer with the refreshed item', async () => {
@@ -2872,70 +2996,93 @@ describe('MCP server integration', () => {
       const backlogOnly = await bootMcpPair({ capabilities: ['backlog:write'] });
       const operatorOnly = await bootMcpPair({ capabilities: ['products:write'] });
 
-      expect(toolNames((await backlogOnly.client.listTools()).tools)).toEqual([
-        'taiga_create_backlog_item',
-        'taiga_move_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 backlogOnly.client.listTools()).tools)).toEqual(['taiga_move_backlog_item']);
+      // A request, the resume and the review gate take a product or an item ID a request or a queue hands
+      // back, so they need no backlog read; the verdicts and Plan again act on what only a read shows.
       expect(toolNames((await operatorOnly.client.listTools()).tools)).toEqual([
+        'taiga_request_initiatives',
         '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 () => {
-      const full = await bootMcpPair({
+    it('should refuse a move into the queue for a key without products:write before any request', async () => {
+      const narrow = await bootMcpPair({ capabilities: ['backlog:read', 'backlog:write'] });
+      const before = narrow.fetchSpy.mock.calls.length;
+
+      const result = await narrow.client.callTool({
+        name: 'taiga_move_backlog_item',
+        arguments: { itemId: ITEM_ID, state: 'queue' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(outcomeOf(result)).toEqual({
+        error: 'FORBIDDEN',
+        message: 'A move into queue starts agent work and needs products:write, which this key lacks.',
+      });
+      expect(narrow.fetchSpy.mock.calls.length).toBe(before);
+    });
+
+    it('should plan again only at the Build station, and point elsewhere at the queue', async () => {
+      const atStation = { ...item, state: 'plan', planningStatus: 'failed' };
+      const station = await bootMcpPair({
         capabilities: ALL_CAPABILITIES,
         routes: {
-          [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: { ...item, state: 'plan', planningStatus: 'planning' } },
+          [`GET /v1/backlog/${ITEM_ID}`]: { data: atStation },
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: { ...atStation, planningStatus: 'planning' } },
         },
       });
-      const planned = await full.client.callTool({
-        name: 'taiga_move_backlog_item',
-        arguments: { itemId: ITEM_ID, state: 'plan' },
+      const replanned = await station.client.callTool({ name: 'taiga_plan_again', arguments: { itemId: ITEM_ID } });
+      expect(replanned.isError).toBeFalsy();
+      expect(sentBody(station.fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'plan' });
+      expect(outcomeOf(replanned)).toMatchObject({ state: 'plan', planningStatus: 'planning' });
+
+      const idle = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { [`GET /v1/backlog/${ITEM_ID}`]: { data: item } },
       });
-      expect(planned.isError).toBeFalsy();
-      expect(sentBody(full.fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'plan' });
-      expect(outcomeOf(planned)).toMatchObject({ state: 'plan', planningStatus: 'planning' });
+      const refused = await idle.client.callTool({ name: 'taiga_plan_again', arguments: { itemId: ITEM_ID } });
+      expect(refused.isError).toBe(true);
+      expect(outcomeOf(refused).message).toMatch(/not at the Build station\. The queue is the only way to start work/);
+      // Refused on the read: no move was sent.
+      expect(idle.fetchSpy.mock.calls.some((c: unknown[]) => (c[1] as RequestInit)?.method === 'PUT')).toBe(false);
+    });
 
-      const narrow = await bootMcpPair({ capabilities: ['backlog:read', 'backlog:write'] });
-      const before = narrow.fetchSpy.mock.calls.length;
-      for (const state of ['queue', 'plan']) {
-        const result = await narrow.client.callTool({
-          name: 'taiga_move_backlog_item',
-          arguments: { itemId: ITEM_ID, state },
-        });
-        expect(result.isError, state).toBe(true);
-        expect(outcomeOf(result)).toEqual({
-          error: 'FORBIDDEN',
-          message: `A move into ${state} starts agent work and needs products:write, which this key lacks.`,
-        });
-      }
-      expect(narrow.fetchSpy.mock.calls.length).toBe(before);
+    it('should plan again past an advisory gate only when force says so', async () => {
+      const atStation = { ...item, state: 'build', planningStatus: 'planned' };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`GET /v1/backlog/${ITEM_ID}`]: { data: atStation },
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: { data: { ...atStation, state: 'plan', planningStatus: 'planning' } },
+        },
+      });
+
+      await client.callTool({ name: 'taiga_plan_again', arguments: { itemId: ITEM_ID, force: true } });
+
+      expect(sentBody(fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'plan', force: true });
     });
 
-    it("should pass on the API's refusal of a create, a resume, a rejection and a run resume alike", async () => {
+    it("should pass on the API's refusal of a request, a resume and a rejection alike", async () => {
       const { client } = await bootMcpPair({
         capabilities: ALL_CAPABILITIES,
         routes: {
-          [`POST /v1/products/${PRODUCT_ID}/backlog`]: refusal(400, 'VALIDATION_ERROR', 'title too long'),
+          'POST /v1/agent-jobs': refusal(409, 'CONFLICT', 'Initiatives are already being generated for this product'),
           [`POST /v1/backlog/${ITEM_ID}/resume`]: refusal(
             409,
             'CONFLICT',
             'This initiative is not stopped, so there is nothing to resume.'
           ),
           [`POST /v1/plans/${PLAN_ID}/reject`]: refusal(409, 'CONFLICT', 'This plan has been replaced'),
-          [`POST /v1/builds/${BUILD_ID}/resume`]: refusal(409, 'CONFLICT', 'Build run is not resumable'),
         },
       });
 
       const calls = [
         [
-          'taiga_create_backlog_item',
-          { productId: PRODUCT_ID, title: 'T', description: 'D' },
-          'VALIDATION_ERROR',
-          'title too long',
+          'taiga_request_initiatives',
+          { productId: PRODUCT_ID, title: 'T' },
+          'CONFLICT',
+          'Initiatives are already being generated for this product',
         ],
         [
           'taiga_resume_backlog_item',
@@ -2944,7 +3091,6 @@ describe('MCP server integration', () => {
           'This initiative is not stopped, so there is nothing to resume.',
         ],
         ['taiga_reject_plan', { planId: PLAN_ID, comment: 'Again' }, 'CONFLICT', 'This plan has been replaced'],
-        ['taiga_resume_build', { buildId: BUILD_ID }, 'CONFLICT', 'Build run is not resumable'],
       ] as const;
       for (const [name, args, error, message] of calls) {
         const result = await client.callTool({ name, arguments: { ...args } });
@@ -3021,20 +3167,23 @@ describe('MCP server integration', () => {
       });
     });
 
-    it('should offer exactly the columns a person may drop into, and refuse build', async () => {
+    it('should offer exactly the columns a person may drop into, and refuse build and plan', async () => {
       const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
 
       const { tools } = await client.listTools();
       const move = tools.find((t) => t.name === 'taiga_move_backlog_item')!;
       const props = move.inputSchema.properties as Record<string, { enum?: string[] }>;
-      expect(props.state!.enum).toEqual(['backlog', 'todo', 'queue', 'done', 'canceled', 'plan']);
+      // The queue is the only way to start work: no "plan this now", nothing dropped into Build.
+      expect(props.state!.enum).toEqual(['backlog', 'todo', 'queue', 'done', 'canceled']);
 
       const before = fetchSpy.mock.calls.length;
-      const result = await client.callTool({
-        name: 'taiga_move_backlog_item',
-        arguments: { itemId: ITEM_ID, state: 'build' },
-      });
-      expect(result.isError).toBe(true);
+      for (const state of ['build', 'plan']) {
+        const result = await client.callTool({
+          name: 'taiga_move_backlog_item',
+          arguments: { itemId: ITEM_ID, state },
+        });
+        expect(result.isError, state).toBe(true);
+      }
       expect(fetchSpy.mock.calls.length).toBe(before);
     });
 
@@ -3161,13 +3310,12 @@ describe('MCP server integration', () => {
       expect(outcomeOf(result)).toEqual({ error: 'CONFLICT', message: 'This plan has been replaced' });
     });
 
-    it('should stop and resume a run and answer with its state and next actions, not its noise', async () => {
+    it('should stop a run and answer with its state and next actions, not its noise', async () => {
       const stopped = { ...run, status: 'stopped', failedReason: 'user_stopped', actions: ['resume', 'start_over'] };
       const { client, fetchSpy } = await bootMcpPair({
         capabilities: ['products:read', 'products:write'],
         routes: {
           [`POST /v1/builds/${BUILD_ID}/stop`]: { data: stopped },
-          [`POST /v1/builds/${BUILD_ID}/resume`]: { data: { ...run, status: 'pending', actions: ['stop'] } },
         },
       });
 
@@ -3186,10 +3334,6 @@ describe('MCP server integration', () => {
       });
       const call = fetchSpy.mock.calls.find((c: unknown[]) => (c[0] as string).endsWith('/stop'))!;
       expect((call[1] as RequestInit).body).toBeNull();
-
-      const resume = await client.callTool({ name: 'taiga_resume_build', arguments: { buildId: BUILD_ID } });
-      expect(resume.isError).toBeFalsy();
-      expect(outcomeOf(resume)).toMatchObject({ status: 'pending', actions: ['stop'] });
     });
 
     it("should pass on the API's refusal to stop a run that is not running", async () => {
@@ -3647,6 +3791,45 @@ describe('MCP server integration', () => {
       );
     });
 
+    it('should pause and resume the line, and say in the queue read that a paused line waits for nothing else', async () => {
+      const paused = { id: PRODUCT_ID, lineStoppedAt: '2026-10-08T20:00:00.000Z' };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read', 'products:write', 'backlog:read'],
+        routes: {
+          [`PUT /v1/products/${PRODUCT_ID}/line`]: { data: paused },
+          [`GET /v1/products/${PRODUCT_ID}`]: { data: paused },
+          [`/v1/products/${PRODUCT_ID}/queue`]: { data: [entry(HEAD_ITEM, 'active')] },
+          [`/v1/backlog/${HEAD_ITEM}`]: { data: head },
+        },
+      });
+
+      const pause = parseToolResult(
+        await client.callTool({ name: 'taiga_pause_line', arguments: { productId: PRODUCT_ID, paused: true } })
+      );
+      expect(sentBody(fetchSpy, 'PUT', '/line')).toEqual({ stopped: true });
+      expect(pause).toEqual({ productId: PRODUCT_ID, linePaused: true, lineStoppedAt: '2026-10-08T20:00:00.000Z' });
+
+      const queue = parseToolResult(
+        await client.callTool({ name: 'taiga_get_queue', arguments: { productId: PRODUCT_ID } })
+      );
+      expect(queue.linePaused).toBe(true);
+
+      // Resuming sends the other answer and reports the line running.
+      fetchSpy.mockClear();
+      fetchSpy.mockImplementation(
+        makeFetchRouter({
+          '/v1/auth/introspect': introspectionResponse(['products:read', 'products:write', 'backlog:read']),
+          [`PUT /v1/products/${PRODUCT_ID}/line`]: { data: { id: PRODUCT_ID, lineStoppedAt: null } },
+        }).getMockImplementation()!
+      );
+      const resumed = parseToolResult(
+        await client.callTool({ name: 'taiga_pause_line', arguments: { productId: PRODUCT_ID, paused: false } })
+      );
+      expect(sentBody(fetchSpy, 'PUT', '/line')).toEqual({ stopped: false });
+      expect(resumed).toEqual({ productId: PRODUCT_ID, linePaused: false, lineStoppedAt: null });
+      expect(queue.waitingOn).toMatch(/^The line is paused \(since 2026-10-08T20:00:00.000Z\)/);
+    });
+
     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.
@@ -4110,6 +4293,26 @@ describe('MCP server integration', () => {
       expect(productCalls).toBe(2);
     });
 
+    it("should wake a wait for any change when a landed plan's review gate is set, though the lifecycle reads the same", async () => {
+      const landed = {
+        ...item,
+        state: 'plan',
+        planningStatus: 'planned',
+        autoBuild: null,
+        lifecycle: { turn: 'you', stage: 'planned', cta: 'start_build', latestBuild: null },
+      };
+      const { client } = await bootMcpPair({
+        capabilities: ['backlog:read'],
+        routes: { [`/v1/backlog/${ITEM_ID}`]: sequence(landed, landed, { ...landed, autoBuild: false }) },
+      });
+
+      const result = parseToolResult(
+        await client.callTool({ name: 'taiga_wait_for_backlog_item', arguments: { itemId: ITEM_ID, until: 'changed' } })
+      );
+
+      expect(result).toMatchObject({ reached: true, item: { autoBuild: false } });
+    });
+
     it('should answer reached: false at the timeout', async () => {
       const { client } = await bootMcpPair({
         capabilities: ['backlog:read'],

package/src/tools/annotations.ts

@@ -30,3 +30,9 @@ export const OPERATE = {
   idempotentHint: false,
   openWorldHint: false,
 } as const;
+
+/**
+ * An OPERATE write that sets a value rather than adding one: the same call
+ * twice leaves things as one call does (a review gate set, a line paused).
+ */
+export const OPERATE_SETTING = { ...OPERATE, idempotentHint: true } as const;