@taiga-ai/mcp-server 0.23.0-rc.460 → 0.24.0-dev.461

package/dist/index.js

@@ -583,14 +583,14 @@ const OPERATE_SETTING = {
 * schema's message, not the description, when a call fails validation, and
 * "Invalid UUID" alone sends a model that passed a name to guess again.
 */
-function idInput(what, from) {
-	return z.string().uuid({ message: `${/^[aeiou]/i.test(what) ? "An" : "A"} ${what} ID is a UUID, not a name: ${from}` }).describe(`${what[0].toUpperCase()}${what.slice(1)} ID -- ${from}`);
+function idInput(what, from, said = from) {
+	return z.string().uuid({ message: `${/^[aeiou]/i.test(what) ? "An" : "A"} ${what} ID is a UUID, not a name: ${from}` }).meta({ pattern: void 0 }).describe(`${what[0].toUpperCase()}${what.slice(1)} ID -- ${said}`);
 }
-const productId = idInput("product", "taiga_list_products (query finds one by name), or taiga_get_product with a git remote URL, gives it");
+const productId = idInput("product", "taiga_list_products (query finds one by name), or taiga_get_product with a git remote URL, gives it", "taiga_list_products gives it");
 /** The page inputs every list tool takes; `nextCursor` of one page is the `cursor` of the next. */
 const pagination = {
 	limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)"),
-	cursor: z.string().max(256).optional().describe("The nextCursor of the previous page, to read the next one; omit for the first page")
+	cursor: z.string().max(256).optional().describe("The previous page's nextCursor; omit for the first page")
 };
 const slug = z.string().max(63).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "A slug is lowercase words joined by hyphens").describe("Product slug, as it appears in Taiga URLs");
 const remoteUrl = z.string().min(1).max(2048).describe("The git remote URL of a checkout (git remote get-url origin): https://, git@host:owner/repo.git or ssh://");
@@ -2278,9 +2278,9 @@ const BY_ARGUMENT = {
 	initiativeId: ITEM_ID_HINT,
 	runId: "taiga_list_runs lists the runs, of one product or of every product the key can see.",
 	planId: "taiga_get_plan gives the initiative's active plan and its ID.",
-	repositoryId: "taiga_list_product_repositories lists the product's repository links; a GitHub repository id is not a link ID.",
+	repositoryId: "taiga_list_product_repositories lists the product's repository links; a linkable repository id is not a link ID.",
 	replacesRepositoryId: "taiga_list_product_repositories lists the product's repository links.",
-	githubRepositoryId: "taiga_list_linkable_repositories lists the repositories the GitHub connection reaches, with their ids.",
+	linkableRepositoryId: "taiga_list_linkable_repositories lists the repositories the GitHub connection reaches, with their ids.",
 	installationId: "taiga_list_linkable_repositories lists the connected GitHub accounts.",
 	jobId: "A job ID is what the tool that started the job returned (taiga_request_initiatives, taiga_start_import).",
 	factoryId: "taiga_list_factories lists the factories the key can see.",
@@ -2307,7 +2307,7 @@ const MISSING_THING = {
 	planId: /\bplan\b/i,
 	repositoryId: /repository link|\blink\b/i,
 	replacesRepositoryId: /repository link|\blink\b/i,
-	githubRepositoryId: /github repository/i,
+	linkableRepositoryId: /github repository/i,
 	installationId: /installation|account/i,
 	jobId: /\bjob\b/i,
 	factoryId: /factory|team/i,
@@ -2365,10 +2365,24 @@ const OPAQUE_MAPS = /* @__PURE__ */ new Set([
 	"settings"
 ]);
 /** A copy of an API value with its keys in the product's words, values untouched. */
+/**
+* Run actions only the web offers (PRO-2800): start_over was listed beside what an agent can call, on runs and on
+* every initiative's latest run, while the descriptions said it was web only. Split apart wherever actions appear.
+*/
+const WEB_ONLY_ACTIONS = /* @__PURE__ */ new Set(["start_over"]);
 function inProductWords(value) {
 	if (Array.isArray(value)) return value.map(inProductWords);
 	if (value === null || typeof value !== "object") return value;
 	const out = {};
+	const actions = value["actions"];
+	if (Array.isArray(actions) && actions.some((action) => WEB_ONLY_ACTIONS.has(String(action)))) {
+		const webOnly = actions.filter((action) => WEB_ONLY_ACTIONS.has(String(action)));
+		value = {
+			...value,
+			actions: actions.filter((action) => !WEB_ONLY_ACTIONS.has(String(action))),
+			webOnlyActions: webOnly
+		};
+	}
 	for (const [key, inner] of Object.entries(value)) Object.defineProperty(out, PRODUCT_WORDS[key] ?? key, {
 		value: OPAQUE_MAPS.has(key) ? inner : inProductWords(inner),
 		enumerable: true,
@@ -2684,6 +2698,24 @@ function controlSections(sections, ids) {
 	return found;
 }
 /**
+* A policy outline names the controls each section states (PRO-2800): a reviewer guessed secretsManagement from its
+* name, which works for secrets and not for "what covers logging of secret access". Read off each section's text.
+*/
+function withControls(outline, sections, policyType) {
+	const pattern = new RegExp(`^\\|\\s*(${CONTROL_ID_SOURCE})\\s*\\|\\s*(.*?)\\s*(?:\\||$)`, "gm");
+	return outline.map((entry) => {
+		const text = sectionContent(sections, entry.id) ?? "";
+		const ids = [...new Set([...text.matchAll(pattern)].filter((match) => !/^_?Reserved_?/i.test(match[2] ?? "")).map((match) => match[1]).filter((id) => {
+			const owner = POLICY_TYPE_BY_CONTROL_PREFIX[id.split("-")[0] ?? ""];
+			return owner === void 0 || owner === policyType;
+		}))];
+		return ids.length > 0 ? {
+			...entry,
+			controls: ids
+		} : entry;
+	});
+}
+/**
 * The answer to a read that names sections: the ones the document has, the
 * rest listed with their sizes, and the asked-for ids it lacks under
 * unknownSections. One shape whatever matched (PRO-2778): a wrong id does not
@@ -2708,7 +2740,7 @@ function sectionReadResult(doc, asked, label, options = {}) {
 		const { data: _data, ...meta } = cut.doc;
 		return toolResult({
 			...meta,
-			outline: cut.omittedSections,
+			outline: options.controlIds && before ? withControls(cut.omittedSections, before, doc.type) : cut.omittedSections,
 			...unknownSections.length > 0 ? { unknownSections } : {},
 			...controlNote
 		});
@@ -3848,6 +3880,20 @@ const STEP_SUMMARY_FIELDS = [
 	"startedAt",
 	"completedAt"
 ];
+/**
+* A step a failed run never reached reads as planned, as it was (PRO-2800): a run rejected before it began showed
+* each step failed with "still in flight", though none had started. The API reaches failed only through in_progress,
+* which sets startedAt, so a failed step without one is a planned step the run's failure swept up.
+*/
+function neverStarted(step) {
+	if (step["status"] !== "failed" || step["startedAt"]) return step;
+	const { error: _error, ...rest } = step;
+	return {
+		...rest,
+		status: "planned",
+		completedAt: null
+	};
+}
 /** Past this many characters a step's headline is cut; the full read has the rest. */
 const HEADLINE_LIMIT = 600;
 /**
@@ -3917,7 +3963,7 @@ function registerBuildTools(server, client) {
 	}));
 	server.registerTool("taiga_get_run", {
 		title: "Get run",
-		description: "Read one run with its steps: outcome, disposition, pull request, hardening, and per step its title, status, commit, files changed, verification and headline (first paragraph of the agent's report). verification is Taiga's own check after the step (tests, lint, build), so a docs-only step can fail on the repository's failing tests (verificationNote says when one failed throughout). A failed or stopped run has stoppedIn, lastProgressAt and failedReasonMeans (what its failedReason means). full: true adds complete instructions and reports. actions: resume and retry_from_failed_step are taiga_resume_initiative; start_over is web only; to stop it, move the initiative out of Build. A maintenance run has no initiative and is retried from its finding.",
+		description: "Read one run with its steps: outcome, disposition, pull request, hardening, and per step its title, status, commit, files changed, verification and headline (first paragraph of the agent's report). verification is Taiga's own check after the step (tests, lint, build), so a docs-only step can fail on the repository's failing tests (verificationNote says when one failed throughout). A failed or stopped run has stoppedIn, lastProgressAt and failedReasonMeans (what its failedReason means). full: true adds complete instructions and reports. actions: resume and retry_from_failed_step are taiga_resume_initiative; webOnlyActions (start_over) are in the web; to stop it, move the initiative out of Build. A maintenance run has no initiative and is retried from its finding.",
 		inputSchema: z.object({
 			runId,
 			full: z.boolean().optional().describe("Carry each step's complete instructions and report (default false: a summary)")
@@ -3926,7 +3972,7 @@ function registerBuildTools(server, client) {
 	}, (params) => runTool(async () => {
 		const [run, steps] = await Promise.all([client.getBuildRun(params.runId), client.listBuildRunSteps(params.runId)]);
 		const runRow = run.data;
-		const rows = steps.data;
+		const rows = steps.data.map((step) => neverStarted(step));
 		const where = stoppedIn(runRow, rows);
 		const stop = where ? { stoppedIn: where } : {};
 		const states = await initiativeStates(client, [runRow]);
@@ -3937,7 +3983,7 @@ function registerBuildTools(server, client) {
 			...readable,
 			...stop,
 			...verification,
-			steps: steps.data
+			steps: rows
 		});
 		return toolResult({
 			...readable,
@@ -4423,13 +4469,22 @@ function registerBacklogReads(server, client) {
 			return toolResult(page(situatedRows(result.data), result.nextCursor));
 		}
 		if (params.cursor !== void 0) return toolError("VALIDATION_ERROR", "Open items, a board column or a title search answer one page; narrow them, or pass status: 'all' (or one status) to page through every item.");
+		let closedSeen = 0;
+		const needle = (query ?? "").toLowerCase();
 		const found = await searchPages((cursor) => client.listBacklogItems(params.productId, {
 			...apiFilters,
 			limit: 100,
 			cursor
-		}), query ?? "", (row) => [row.title], params.limit ?? 25, (row) => (state === void 0 || row.state === state) && (!open || !["done", "canceled"].includes(row.status)));
+		}), query ?? "", (row) => [row.title], params.limit ?? 25, (row) => {
+			if (state !== void 0 && row.state !== state) return false;
+			if (!open || !["done", "canceled"].includes(row.status)) return true;
+			if (query !== void 0 && String(row.title).toLowerCase().includes(needle)) closedSeen += 1;
+			return false;
+		});
+		const hidden = query !== void 0 && state === void 0 && !found.more ? closedSeen : 0;
 		return toolResult({
 			...page(situatedRows(found.rows), null),
+			...hidden > 0 ? { closedMatches: `${hidden} done or canceled initiative${hidden === 1 ? " also matches" : "s also match"}; status: 'all' lists them.` } : {},
 			...found.more ? { more: "There may be more than the limit carries: narrow it with state or query, or list one status (backlog, in_progress, done or canceled) without them, which pages." } : {}
 		});
 	}));
@@ -4806,7 +4861,8 @@ function registerMaintenanceTools(server, client) {
 				sweepNote: "The sweep overview could not be read: an empty list here is not an all-clear."
 			} : sweep ? { sweep } : {},
 			...page(pickFields(result.data, FINDING_ROW_FIELDS).map(withFixability), result.nextCursor),
-			...typeof result.totalCount === "number" ? { totalCount: result.totalCount } : {}
+			...typeof result.totalCount === "number" ? { totalCount: result.totalCount } : {},
+			...params.status === void 0 && params.severity === void 0 && params.kind === void 0 && typeof result.totalCount === "number" && sweep && sweep !== "unread" && typeof sweep["openFindings"] === "number" && sweep["openFindings"] !== result.totalCount ? { totalNote: "totalCount includes findings with a fix under way (remediating) and ignored findings whose ignore has expired; sweep.openFindings counts open ones only." } : {}
 		});
 	}));
 	server.registerTool("taiga_get_finding", {
@@ -4988,7 +5044,10 @@ function readWith(row, backlogRead) {
 	switch (row["subjectType"]) {
 		case "build_run": return "taiga_get_run (runId: subjectId)";
 		case "backlog_item": return backlogRead ? "taiga_get_plan (initiativeId: subjectId)" : void 0;
-		case "product_document": return "taiga_list_product_documents (productId)";
+		case "product_document": {
+			const type = /^[^:]+:([a-z_]+):decision:/.exec(String(row["subjectId"]))?.[1];
+			return type ? `taiga_get_product_document (productId, type: ${type}); the decision's text is this row with full: true` : "taiga_list_product_documents (productId)";
+		}
 		case "inbox_task": return "taiga_list_setup_tasks (productId)";
 		case "product": return {
 			review_backlog: backlogRead ? "taiga_list_initiatives (productId)" : void 0,
@@ -5270,6 +5329,7 @@ function registerInboxTools(server, client) {
 				} : item;
 			}), result.nextCursor),
 			...totalOf(result),
+			...overview && typeof result.totalCount === "number" && (stale.size > 0 || overview.data.length > overviewDue.length || overview.nextCursor) ? { totalNote: "totalCount counts every item, stale and snoozed ones too; summary.open does not" + (overview.nextCursor ? `, and counts only the first ${SUMMARY_PAGE}.` : ".") } : {},
 			...hidden > 0 ? { snoozedHidden: hidden } : {},
 			...checked.unchecked > 0 ? { staleNote: `${checked.unchecked} review${checked.unchecked === 1 ? " was" : "s were"} not checked for staleness (past the cap, or the read was refused).` } : {}
 		});
@@ -21012,7 +21072,7 @@ const GITHUB_REPOSITORY_FIELDS = [
 	"language",
 	"linked"
 ];
-const repositoryId = idInput("repository link", "taiga_list_product_repositories gives it; a GitHub repository id is not one");
+const repositoryId = idInput("repository link", "taiga_list_product_repositories gives it; a linkable repository id is not one");
 /** Round-robin over lists: the first of each, then the second of each, and so on. */
 function interleave(lists) {
 	const out = [];
@@ -21021,6 +21081,28 @@ function interleave(lists) {
 	return out;
 }
 /**
+* A repository linked elsewhere names the product that holds it (PRO-2800): the API says "another product", and a
+* reviewer spent a call finding which. One read, the products the key can see; null leaves the API's refusal.
+*/
+async function holderOf(client, error, productId) {
+	if (!(error instanceof TaigaApiError) || error.status !== 409) return null;
+	const name = /^(\S+\/\S+) is already linked to another product\.?$/.exec(error.apiMessage ?? "")?.[1];
+	if (!name) return null;
+	try {
+		const holders = (await client.listProducts({
+			repository: name,
+			limit: 20
+		})).data.filter((p) => p.id !== productId);
+		return toolError("CONFLICT", `${name} is already linked to another product. ${holders.length > 0 ? `Products this key can see with a repository named ${name}: ${holders.map((p) => `${p.name} (${p.id})`).join(", ")}.` : "It is linked to a product this key cannot see."} A repository belongs to one product; unlink it there first (taiga_unlink_repository) if this product should have it.`, { holders: holders.map((p) => ({
+			productId: p.id,
+			name: p.name
+		})) });
+	} catch (inner) {
+		if (inner instanceof TaigaApiError || isNetworkFailure(inner)) return null;
+		throw inner;
+	}
+}
+/**
 * A product in setup says what it still needs after a repository write, as create_product and get_product do
 * (PRO-2800): a reviewer had to read the product again to learn that the import came next. Best effort: the write
 * is done, so a failed read leaves readiness out rather than failing it.
@@ -21066,7 +21148,7 @@ function registerRepositoryTools(server, client) {
 	}
 	if (client.hasCapability("vcs:read")) server.registerTool("taiga_list_linkable_repositories", {
 		title: "Find a repository to link",
-		description: "List the repositories the organization's GitHub connection can reach, to link one with taiga_link_repository (it takes the row's id: Taiga's record of the repository, not GitHub's numeric id, and not a link ID). query searches by name; account (login, owner, or installationId) reads one account, else rows come from every account in turn. linked: true means a product already links it (taiga_get_product with its URL says which). No connection means GitHub is not connected yet; someone who can install the app does that once, in the web.",
+		description: "List the repositories the organization's GitHub connection can reach, to link one with taiga_link_repository (it takes the row's id as linkableRepositoryId). query searches by name; account (login, owner, or installationId) reads one account, else rows come from every account in turn. linked: true means a product already links it (taiga_get_product with its URL says which). No connection means GitHub is not connected yet; someone who can install the app does that once, in the web.",
 		inputSchema: z.object({
 			query: z.string().trim().min(1).max(256).optional().describe("Part of the repository name"),
 			account: z.string().trim().min(1).max(140).optional().describe("The GitHub account login (the owner in owner/repo), case-insensitive"),
@@ -21116,16 +21198,24 @@ function registerRepositoryTools(server, client) {
 		description: "Link a GitHub repository to a product (taiga_list_linkable_repositories gives its id). replacesRepositoryId swaps out the one linked now in one step (the same one changes nothing); linking while one is linked without it is refused. A managed link (isManaged) cannot be replaced or unlinked. Once linked, planning reads its code, runs open pull requests in it, sweeps scan it, and its deployment history is imported.",
 		inputSchema: z.object({
 			productId,
-			githubRepositoryId: idInput("GitHub repository", "taiga_list_linkable_repositories gives it (the row's id, Taiga's record; not GitHub's numeric id)"),
+			linkableRepositoryId: idInput("linkable repository", "taiga_list_linkable_repositories gives it (a row's id; not GitHub's numeric id, not a link ID)"),
 			replacesRepositoryId: repositoryId.optional().describe("The link this one replaces")
 		}),
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
-		return toolResult({
-			...pickFields([(await client.linkRepository(params.productId, {
-				githubRepositoryId: params.githubRepositoryId,
+		let linked;
+		try {
+			linked = await client.linkRepository(params.productId, {
+				githubRepositoryId: params.linkableRepositoryId,
 				...params.replacesRepositoryId ? { replacesRepositoryId: params.replacesRepositoryId } : {}
-			})).data], LINK_FIELDS)[0],
+			});
+		} catch (error) {
+			const holder = await holderOf(client, error, params.productId);
+			if (holder) return holder;
+			throw error;
+		}
+		return toolResult({
+			...pickFields([linked.data], LINK_FIELDS)[0],
 			...await readinessAfter(client, params.productId)
 		});
 	}));
@@ -22090,8 +22180,8 @@ function registerWhoami(server, client, registered) {
 * (PRO-2800).
 */
 const SERVER_INSTRUCTIONS = [
-	"Taiga is a policy-aware software delivery platform. Use these tools (taiga_*) when the person asks about a Taiga",
-	"product, its initiatives or runs, policies, findings, deployments, or setting a product up.",
+	"Taiga is a policy-aware software delivery platform. Use these tools (taiga_*) for anything about a Taiga",
+	"product: its initiatives, runs, policies, findings, deployments or setup.",
 	"",
 	"**Which read.** Where a product stands (counts, not detail): taiga_get_product_context, by git remote URL, slug",
 	"or ID. What waits on people: taiga_list_action_required. A policy: taiga_get_document (sections: [], or a",
@@ -22104,17 +22194,17 @@ const SERVER_INSTRUCTIONS = [
 	"a person makes; a sweep is a scan for findings; standing is how a product meets the policies. Discovery is the web",
 	"conversation that specifies a new product. A factory owns products. People stamp checks in the web.",
 	"",
-	"**IDs** are UUIDs; the product, factory and initiative lists take query to find one by name. A NOT_FOUND names the tool that lists the right",
-	"ones. Lists page with nextCursor. outcome, situation and nextStep are one-sentence summaries; setup writes",
-	"return readiness with nextStep, so there is no need to read the product again. A product document has two",
-	"timelines: plan (what was meant) and reality (derived from the code).",
+	"**IDs** are UUIDs; the product, factory and initiative lists take query to find one by name. A NOT_FOUND names",
+	"the tool that lists the right ones. Lists page with nextCursor; taiga_list_initiatives lists open ones unless",
+	"status: 'all'. outcome, situation and nextStep are one-sentence summaries; setup writes return readiness. A",
+	"product document has two timelines: plan (what was meant) and reality (derived from the code).",
 	"",
 	"**Writing.** A tool that writes opens with \"Writes.\", \"Ask first (paid agent work).\" or \"Ask first (others",
 	"see it).\"; before an ask-first tool, tell the person and wait for their yes. Others share the organization: a",
 	"taken name is refused unless allowDuplicateName, and the one that exists may not be this person's.",
 	"",
-	"**Only in the web:** connecting GitHub, members and roles, Discovery, stamping checks, starting a run over, and",
-	"deleting factories and products."
+	"**Only in the web:** connecting GitHub, members and roles, the Discovery conversation, stamping checks, starting",
+	"a run over, and deleting factories and products."
 ].join("\n");
 //#endregion
 //#region src/server.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.23.0-rc.460",
+  "version": "0.24.0-dev.461",
   "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

@@ -3553,7 +3553,9 @@ describe('MCP server integration', () => {
         completedSteps: 1,
         totalSteps: 3,
         prUrl: null,
-        actions: ['resume', 'start_over'],
+        // start_over is the web's, said apart from what this server can call.
+        actions: ['resume'],
+        webOnlyActions: ['start_over'],
         disposition: 'stopped',
         outcome: 'Stopped before it finished (1 of 3 steps done).',
       });
@@ -6000,7 +6002,7 @@ describe('MCP server integration', () => {
       );
       await client.callTool({
         name: 'taiga_link_repository',
-        arguments: { productId: PRODUCT_ID, githubRepositoryId: GH_REPO_ID },
+        arguments: { productId: PRODUCT_ID, linkableRepositoryId: GH_REPO_ID },
       });
       const set = parseToolResult(
         await client.callTool({
@@ -6209,7 +6211,7 @@ describe('MCP server integration', () => {
       });
       const link = await client.callTool({
         name: 'taiga_link_repository',
-        arguments: { productId: PRODUCT_ID, githubRepositoryId: GH_REPO_ID },
+        arguments: { productId: PRODUCT_ID, linkableRepositoryId: GH_REPO_ID },
       });
 
       expect(finish.isError).toBe(true);
@@ -6433,7 +6435,7 @@ describe('what the agent review found (PRO-2759)', () => {
     // The API names the link, so only the link is hinted: the product the call
     // also named was right, and its hint read as blaming it (PRO-2800).
     expect(parseToolResult(branches).message).toBe(
-      "Repository link not found. taiga_list_product_repositories lists the product's repository links; a GitHub " +
+      "Repository link not found. taiga_list_product_repositories lists the product's repository links; a linkable " +
         'repository id is not a link ID.'
     );
   });
@@ -6456,7 +6458,7 @@ describe('what the agent review found (PRO-2759)', () => {
     });
     expect(parseToolResult(branches).message).toBe(
       "The requested resource does not exist. taiga_list_product_repositories lists the product's repository " +
-        'links; a GitHub repository id is not a link ID. taiga_list_products lists the products the key can see; ' +
+        'links; a linkable repository id is not a link ID. taiga_list_products lists the products the key can see; ' +
         'a name is not an ID (taiga_get_product takes a slug).'
     );
   });
@@ -8253,7 +8255,7 @@ describe('what the fourth agent review found (PRO-2800)', () => {
     const linked = parseToolResult(
       await client.callTool({
         name: 'taiga_link_repository',
-        arguments: { productId: PRODUCT_ID, githubRepositoryId: '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4f07' },
+        arguments: { productId: PRODUCT_ID, linkableRepositoryId: '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4f07' },
       })
     );
     expect(linked.readiness?.nextStep).toEqual(expect.any(String));
@@ -8271,7 +8273,7 @@ describe('what the fourth agent review found (PRO-2800)', () => {
     const refused = parseToolResult(
       await second.callTool({
         name: 'taiga_link_repository',
-        arguments: { productId: PRODUCT_ID, githubRepositoryId: '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4f07' },
+        arguments: { productId: PRODUCT_ID, linkableRepositoryId: '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4f07' },
       })
     );
     expect(refused.message).toBe(
@@ -8590,3 +8592,225 @@ describe('what the sixth agent review found (PRO-2800)', () => {
     expect(run).not.toHaveProperty('runtime');
   });
 });
+
+describe('what the seventh agent review found (PRO-2800)', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('says an ID is a UUID by format, not by a pattern repeated on every ID', async () => {
+    const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+
+    const { tools } = await client.listTools();
+    const listing = JSON.stringify(tools);
+    const refused = await client.callTool({ name: 'taiga_get_initiative', arguments: { initiativeId: 'my item' } });
+
+    expect(listing).not.toMatch(/"pattern":"\^\(\[0-9a-fA-F\]\{8\}/);
+    expect(listing).toMatch(/"format":"uuid"/);
+    expect(JSON.stringify(refused.content)).toMatch(/An initiative ID is a UUID/);
+  });
+
+  it('says when a title search under the open default also matches done or canceled initiatives', async () => {
+    const row = (id: string, title: string, status: string) => ({ id, title, status, state: status });
+    const { client } = await bootMcpPair({
+      capabilities: ['backlog:read'],
+      routes: {
+        [`/v1/products/${PRODUCT_ID}/backlog`]: {
+          data: [
+            row('a', 'Secret detection in CI', 'done'),
+            row('b', 'Secret detection v2', 'canceled'),
+            row('c', 'Docs', 'backlog'),
+          ],
+          nextCursor: null,
+        },
+      },
+    });
+
+    const result = parseToolResult(
+      await client.callTool({
+        name: 'taiga_list_initiatives',
+        arguments: { productId: PRODUCT_ID, query: 'secret detection' },
+      })
+    );
+
+    expect(result.data).toEqual([]);
+    expect(result.closedMatches).toBe("2 done or canceled initiatives also match; status: 'all' lists them.");
+  });
+
+  it('shows a step a failed run never reached as planned, and stoppedIn agrees', async () => {
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read'],
+      routes: {
+        [`/v1/builds/${BUILD_ID}/steps`]: {
+          data: [
+            {
+              id: 's1',
+              stepOrder: 1,
+              title: 'One',
+              status: 'failed',
+              startedAt: null,
+              completedAt: '2026-10-10T10:00:00Z',
+              error: 'still in flight',
+            },
+          ],
+        },
+        [`/v1/builds/${BUILD_ID}`]: {
+          data: { id: BUILD_ID, productId: PRODUCT_ID, status: 'failed', failedReason: 'dispatch_rejected' },
+        },
+      },
+    });
+
+    const run = parseToolResult(await client.callTool({ name: 'taiga_get_run', arguments: { runId: BUILD_ID } }));
+
+    expect(run.steps[0].status).toBe('planned');
+    expect(run.steps[0].completedAt).toBeNull();
+    expect(run.steps[0]).not.toHaveProperty('error');
+    // stoppedIn reads the same steps, so it says the run stopped before any began.
+    expect(run.stoppedIn).toMatch(/^before the first step started/);
+  });
+
+  it("names the document a document decision is about, since its subject id is no tool's input", async () => {
+    const { client } = await bootMcpPair({
+      capabilities: ['products:read'],
+      routes: {
+        'GET /v1/inbox': {
+          data: [
+            {
+              id: 'd1',
+              productId: PRODUCT_ID,
+              kind: 'review_doc',
+              subjectType: 'product_document',
+              subjectId: `${PRODUCT_ID}:risk_register:decision:b389e792d793`,
+              title: 'Decide',
+              status: 'open',
+              createdAt: new Date().toISOString(),
+            },
+          ],
+          nextCursor: null,
+        },
+      },
+    });
+
+    const list = parseToolResult(await client.callTool({ name: 'taiga_list_action_required', arguments: {} }));
+
+    expect(list.data[0].readWith).toBe(
+      "taiga_get_product_document (productId, type: risk_register); the decision's text is this row with full: true"
+    );
+  });
+
+  it('names the controls each section of a policy outline states', async () => {
+    const { client } = await bootMcpPair({
+      capabilities: ALL_CAPABILITIES,
+      routes: {
+        'GET /v1/tenants/current/documents/policy_security': {
+          data: {
+            id: 'p',
+            type: 'policy_security',
+            version: 1,
+            isDraft: false,
+            data: {
+              sections: {
+                scope: { content: 'All systems.' },
+                secretsManagement: { content: '| SEC-5.1 | Vault |\n| SEC-5.3 | Log access | see SEC-5.1. |' },
+                telecom: { content: '| TEL-TIC-1.1 | Lawful intercept |\n| TEL-TIC-1.2 | _Reserved_ |' },
+                // A data control in the security policy is a stale mention, not this policy's control.
+                stray: { content: '| DATA-1.1 | Classify data |' },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    const outline = parseToolResult(
+      await client.callTool({ name: 'taiga_get_document', arguments: { type: 'policy_security', sections: [] } })
+    ).outline;
+
+    expect(outline.map((entry: { id: string; controls?: string[] }) => [entry.id, entry.controls ?? []])).toEqual([
+      ['scope', []],
+      ['secretsManagement', ['SEC-5.1', 'SEC-5.3']],
+      ['telecom', ['TEL-TIC-1.1']],
+      ['stray', []],
+    ]);
+  });
+
+  it('names the product a repository is already linked to', async () => {
+    const { client } = await bootMcpPair({
+      capabilities: ALL_CAPABILITIES,
+      routes: {
+        [`POST /v1/products/${PRODUCT_ID}/repositories`]: refusal(
+          409,
+          'CONFLICT',
+          'taiga-sandbox/import-test-chi is already linked to another product.'
+        ),
+        'GET /v1/products': { data: [{ id: PRODUCT_ID_2, name: 'Imported' }], nextCursor: null },
+      },
+    });
+
+    const result = parseToolResult(
+      await client.callTool({
+        name: 'taiga_link_repository',
+        arguments: { productId: PRODUCT_ID, linkableRepositoryId: '0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4f07' },
+      })
+    );
+
+    expect(result.error).toBe('CONFLICT');
+    expect(result.message).toMatch(
+      new RegExp(
+        `Products this key can see with a repository named taiga-sandbox/import-test-chi: Imported \\(${PRODUCT_ID_2}\\)\\.`
+      )
+    );
+    expect(result.details.holders).toEqual([{ productId: PRODUCT_ID_2, name: 'Imported' }]);
+  });
+
+  it('says what totalCount counts beside an Action Required summary that counts differently, and only then', async () => {
+    const item = (id: string, extra: Record<string, unknown> = {}) => ({
+      id,
+      productId: PRODUCT_ID,
+      productName: 'Web',
+      kind: 'setup_secret',
+      subjectType: 'inbox_task',
+      subjectId: id,
+      title: id,
+      status: 'open',
+      createdAt: new Date().toISOString(),
+      ...extra,
+    });
+    const boot = (data: unknown[]) =>
+      bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { 'GET /v1/inbox': { data, nextCursor: null, totalCount: data.length } },
+      });
+
+    const plain = await boot([item('a'), item('b')]);
+    const quiet = parseToolResult(await plain.client.callTool({ name: 'taiga_list_action_required', arguments: {} }));
+    const snoozed = await boot([item('a'), item('b', { status: 'snoozed', snoozedUntil: '2999-01-01T00:00:00Z' })]);
+    const said = parseToolResult(await snoozed.client.callTool({ name: 'taiga_list_action_required', arguments: {} }));
+
+    expect(quiet).not.toHaveProperty('totalNote');
+    expect(said.totalNote).toBe('totalCount counts every item, stale and snoozed ones too; summary.open does not.');
+  });
+
+  it('says what the findings totalCount counts beside the sweep count, unfiltered only', async () => {
+    const routes = {
+      [`/v1/products/${PRODUCT_ID}/maintenance/findings`]: { data: [{ id: 'f1' }], nextCursor: null, totalCount: 33 },
+      [`/v1/products/${PRODUCT_ID}/maintenance/summary`]: { data: { openFindings: 31 } },
+      [`/v1/products/${PRODUCT_ID}/maintenance/runs`]: { data: [{ id: 's1', status: 'completed' }], nextCursor: null },
+    };
+    const { client } = await bootMcpPair({ capabilities: ['products:read'], routes });
+
+    const all = parseToolResult(
+      await client.callTool({ name: 'taiga_list_findings', arguments: { productId: PRODUCT_ID } })
+    );
+    const critical = parseToolResult(
+      await client.callTool({ name: 'taiga_list_findings', arguments: { productId: PRODUCT_ID, severity: 'critical' } })
+    );
+    const secrets = parseToolResult(
+      await client.callTool({ name: 'taiga_list_findings', arguments: { productId: PRODUCT_ID, kind: 'secret' } })
+    );
+
+    expect(all.totalNote).toMatch(/^totalCount includes findings with a fix under way/);
+    expect(critical).not.toHaveProperty('totalNote');
+    expect(secrets).not.toHaveProperty('totalNote');
+  });
+});

package/src/tools/backlogs.ts

@@ -369,15 +369,31 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
               '(or one status) to page through every item.'
           );
         }
+        // A title search under the open default said nothing of the done and canceled ones it matched: a
+        // reviewer searched "secret detection", got [], and concluded the work never existed (PRO-2800). Counted
+        // in the same pass; exact when the pass read every page.
+        let closedSeen = 0;
+        const needle = (query ?? '').toLowerCase();
         const found = await searchPages(
           (cursor) => client.listBacklogItems(params.productId, { ...apiFilters, limit: SEARCH_PAGE_SIZE, cursor }),
           query ?? '',
           (row) => [row.title],
           params.limit ?? 25,
-          (row) => (state === undefined || row.state === state) && (!open || !['done', 'canceled'].includes(row.status))
+          (row) => {
+            if (state !== undefined && row.state !== state) return false;
+            if (!open || !['done', 'canceled'].includes(row.status)) return true;
+            if (query !== undefined && String(row.title).toLowerCase().includes(needle)) closedSeen += 1;
+            return false;
+          }
         );
+        const hidden = query !== undefined && state === undefined && !found.more ? closedSeen : 0;
         return toolResult({
           ...page(situatedRows(found.rows), null),
+          ...(hidden > 0
+            ? {
+                closedMatches: `${hidden} done or canceled initiative${hidden === 1 ? ' also matches' : 's also match'}; status: 'all' lists them.`,
+              }
+            : {}),
           ...(found.more
             ? {
                 more:

package/src/tools/builds.ts

@@ -403,6 +403,18 @@ const STEP_SUMMARY_FIELDS = [
   'completedAt',
 ] as const;
 
+/**
+ * A step a failed run never reached reads as planned, as it was (PRO-2800): a run rejected before it began showed
+ * each step failed with "still in flight", though none had started. The API reaches failed only through in_progress,
+ * which sets startedAt, so a failed step without one is a planned step the run's failure swept up.
+ */
+function neverStarted(step: Record<string, unknown>): Record<string, unknown> {
+  if (step['status'] !== 'failed' || step['startedAt']) return step;
+  // The sweep also stamped completedAt and an error; a planned step has neither.
+  const { error: _error, ...rest } = step;
+  return { ...rest, status: 'planned', completedAt: null };
+}
+
 /** Past this many characters a step's headline is cut; the full read has the rest. */
 const HEADLINE_LIMIT = 600;
 
@@ -540,7 +552,7 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
         "the repository's failing tests (verificationNote says when one failed throughout). A failed or stopped " +
         'run has stoppedIn, lastProgressAt and failedReasonMeans (what its failedReason means). full: true ' +
         'adds complete instructions and reports. actions: resume and retry_from_failed_step are ' +
-        'taiga_resume_initiative; start_over is web only; to stop it, move the initiative out of Build. A ' +
+        'taiga_resume_initiative; webOnlyActions (start_over) are in the web; to stop it, move the initiative out of Build. A ' +
         'maintenance run has no initiative and is retried from its finding.',
       inputSchema: z.object({
         runId,
@@ -560,14 +572,17 @@ export function registerBuildTools(server: McpServer, client: TaigaClient) {
           client.listBuildRunSteps(params.runId),
         ]);
         const runRow = run.data;
-        const rows = steps.data;
+        // Steps a failed run never reached read as planned before anything else reads them, stoppedIn included.
+        const rows = steps.data.map((step) =>
+          neverStarted(step as unknown as Record<string, unknown>)
+        ) as unknown as typeof steps.data;
         const where = stoppedIn(runRow, rows);
         const stop = where ? { stoppedIn: where } : {};
         const states = await initiativeStates(client, [runRow as unknown as Record<string, unknown>]);
         const readable = withInitiativeState(readableRun(runRow), states);
         const note = verificationNote(rows as unknown as Record<string, unknown>[]);
         const verification = note ? { verificationNote: note } : {};
-        if (params.full) return toolResult({ ...readable, ...stop, ...verification, steps: steps.data });
+        if (params.full) return toolResult({ ...readable, ...stop, ...verification, steps: rows });
         return toolResult({
           ...readable,
           ...stop,

package/src/tools/errors.ts

@@ -23,11 +23,26 @@ const PRODUCT_WORDS: Record<string, string> = {
 const OPAQUE_MAPS = new Set(['sections', 'metadata', 'settings']);
 
 /** A copy of an API value with its keys in the product's words, values untouched. */
+/**
+ * Run actions only the web offers (PRO-2800): start_over was listed beside what an agent can call, on runs and on
+ * every initiative's latest run, while the descriptions said it was web only. Split apart wherever actions appear.
+ */
+const WEB_ONLY_ACTIONS = new Set(['start_over']);
+
 export function inProductWords(value: unknown): unknown {
   if (Array.isArray(value)) return value.map(inProductWords);
   if (value === null || typeof value !== 'object') return value;
   const out: Record<string, unknown> = {};
-  for (const [key, inner] of Object.entries(value)) {
+  const actions = (value as Record<string, unknown>)['actions'];
+  if (Array.isArray(actions) && actions.some((action) => WEB_ONLY_ACTIONS.has(String(action)))) {
+    const webOnly = actions.filter((action) => WEB_ONLY_ACTIONS.has(String(action)));
+    value = {
+      ...(value as Record<string, unknown>),
+      actions: actions.filter((action) => !WEB_ONLY_ACTIONS.has(String(action))),
+      webOnlyActions: webOnly,
+    };
+  }
+  for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
     Object.defineProperty(out, PRODUCT_WORDS[key] ?? key, {
       value: OPAQUE_MAPS.has(key) ? inner : inProductWords(inner),
       enumerable: true,

package/src/tools/hints.ts

@@ -14,9 +14,9 @@ const BY_ARGUMENT: Record<string, string> = {
   runId: 'taiga_list_runs lists the runs, of one product or of every product the key can see.',
   planId: "taiga_get_plan gives the initiative's active plan and its ID.",
   repositoryId:
-    "taiga_list_product_repositories lists the product's repository links; a GitHub repository id is not a link ID.",
+    "taiga_list_product_repositories lists the product's repository links; a linkable repository id is not a link ID.",
   replacesRepositoryId: "taiga_list_product_repositories lists the product's repository links.",
-  githubRepositoryId:
+  linkableRepositoryId:
     'taiga_list_linkable_repositories lists the repositories the GitHub connection reaches, with their ids.',
   installationId: 'taiga_list_linkable_repositories lists the connected GitHub accounts.',
   jobId: 'A job ID is what the tool that started the job returned (taiga_request_initiatives, taiga_start_import).',
@@ -57,7 +57,7 @@ const MISSING_THING: Record<string, RegExp> = {
   planId: /\bplan\b/i,
   repositoryId: /repository link|\blink\b/i,
   replacesRepositoryId: /repository link|\blink\b/i,
-  githubRepositoryId: /github repository/i,
+  linkableRepositoryId: /github repository/i,
   installationId: /installation|account/i,
   jobId: /\bjob\b/i,
   factoryId: /factory|team/i,

package/src/tools/inbox.ts

@@ -57,8 +57,14 @@ function readWith(row: Row, backlogRead: boolean): string | undefined {
     case 'backlog_item':
       // Only a tool the key has: the backlog reads need backlog:read.
       return backlogRead ? 'taiga_get_plan (initiativeId: subjectId)' : undefined;
-    case 'product_document':
-      return 'taiga_list_product_documents (productId)';
+    case 'product_document': {
+      // A document decision's subject is "<productId>:<type>:decision:<hash>", which no tool takes: name the
+      // document it is about, and say where the decision's own text is.
+      const type = /^[^:]+:([a-z_]+):decision:/.exec(String(row['subjectId']))?.[1];
+      return type
+        ? `taiga_get_product_document (productId, type: ${type}); the decision's text is this row with full: true`
+        : 'taiga_list_product_documents (productId)';
+    }
     case 'inbox_task':
       return 'taiga_list_setup_tasks (productId)';
     case 'product':
@@ -433,6 +439,17 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
             result.nextCursor
           ),
           ...totalOf(result),
+          // totalCount is the API's, every item; the summary's open leaves stale and put-off ones out. A reviewer
+          // summed one and compared it with the other (68 against 63).
+          ...(overview &&
+          typeof result.totalCount === 'number' &&
+          (stale.size > 0 || overview.data.length > overviewDue.length || overview.nextCursor)
+            ? {
+                totalNote:
+                  'totalCount counts every item, stale and snoozed ones too; summary.open does not' +
+                  (overview.nextCursor ? `, and counts only the first ${SUMMARY_PAGE}.` : '.'),
+              }
+            : {}),
           ...(hidden > 0 ? { snoozedHidden: hidden } : {}),
           // Past the cap a review is not checked, so no stale on it is not "live".
           ...(checked.unchecked > 0

package/src/tools/inputs.ts

@@ -7,26 +7,29 @@ import { z } from 'zod';
  * schema's message, not the description, when a call fails validation, and
  * "Invalid UUID" alone sends a model that passed a name to guess again.
  */
-export function idInput(what: string, from: string) {
-  return z
-    .string()
-    .uuid({ message: `${/^[aeiou]/i.test(what) ? 'An' : 'A'} ${what} ID is a UUID, not a name: ${from}` })
-    .describe(`${what[0]!.toUpperCase()}${what.slice(1)} ID -- ${from}`);
+export function idInput(what: string, from: string, said: string = from) {
+  return (
+    z
+      .string()
+      .uuid({ message: `${/^[aeiou]/i.test(what) ? 'An' : 'A'} ${what} ID is a UUID, not a name: ${from}` })
+      // format: uuid says it; the 190-character pattern zod adds beside it, on every ID of 79 tools, was the bulk
+      // of the schema a reviewer loaded (PRO-2800). Validation is unchanged.
+      .meta({ pattern: undefined })
+      .describe(`${what[0]!.toUpperCase()}${what.slice(1)} ID -- ${said}`)
+  );
 }
 
 export const productId = idInput(
   'product',
-  'taiga_list_products (query finds one by name), or taiga_get_product with a git remote URL, gives it'
+  'taiga_list_products (query finds one by name), or taiga_get_product with a git remote URL, gives it',
+  // On 39 tools: the full sentence is the refusal's, where it is needed.
+  'taiga_list_products gives it'
 );
 
 /** The page inputs every list tool takes; `nextCursor` of one page is the `cursor` of the next. */
 export const pagination = {
   limit: z.number().int().min(1).max(100).optional().describe('Max results (default 25)'),
-  cursor: z
-    .string()
-    .max(256)
-    .optional()
-    .describe('The nextCursor of the previous page, to read the next one; omit for the first page'),
+  cursor: z.string().max(256).optional().describe("The previous page's nextCursor; omit for the first page"),
 };
 
 export const slug = z

package/src/tools/instructions.ts

@@ -10,8 +10,8 @@
  * (PRO-2800).
  */
 export const SERVER_INSTRUCTIONS = [
-  'Taiga is a policy-aware software delivery platform. Use these tools (taiga_*) when the person asks about a Taiga',
-  'product, its initiatives or runs, policies, findings, deployments, or setting a product up.',
+  'Taiga is a policy-aware software delivery platform. Use these tools (taiga_*) for anything about a Taiga',
+  'product: its initiatives, runs, policies, findings, deployments or setup.',
   '',
   '**Which read.** Where a product stands (counts, not detail): taiga_get_product_context, by git remote URL, slug',
   'or ID. What waits on people: taiga_list_action_required. A policy: taiga_get_document (sections: [], or a',
@@ -24,17 +24,17 @@ export const SERVER_INSTRUCTIONS = [
   'a person makes; a sweep is a scan for findings; standing is how a product meets the policies. Discovery is the web',
   'conversation that specifies a new product. A factory owns products. People stamp checks in the web.',
   '',
-  '**IDs** are UUIDs; the product, factory and initiative lists take query to find one by name. A NOT_FOUND names the tool that lists the right',
-  'ones. Lists page with nextCursor. outcome, situation and nextStep are one-sentence summaries; setup writes',
-  'return readiness with nextStep, so there is no need to read the product again. A product document has two',
-  'timelines: plan (what was meant) and reality (derived from the code).',
+  '**IDs** are UUIDs; the product, factory and initiative lists take query to find one by name. A NOT_FOUND names',
+  'the tool that lists the right ones. Lists page with nextCursor; taiga_list_initiatives lists open ones unless',
+  "status: 'all'. outcome, situation and nextStep are one-sentence summaries; setup writes return readiness. A",
+  'product document has two timelines: plan (what was meant) and reality (derived from the code).',
   '',
   '**Writing.** A tool that writes opens with "Writes.", "Ask first (paid agent work)." or "Ask first (others',
   'see it)."; before an ask-first tool, tell the person and wait for their yes. Others share the organization: a',
   "taken name is refused unless allowDuplicateName, and the one that exists may not be this person's.",
   '',
-  '**Only in the web:** connecting GitHub, members and roles, Discovery, stamping checks, starting a run over, and',
-  'deleting factories and products.',
+  '**Only in the web:** connecting GitHub, members and roles, the Discovery conversation, stamping checks, starting',
+  'a run over, and deleting factories and products.',
 ].join('\n');
 
 /** The most the instructions may take: Claude Code cuts each server's at 2,048 characters. */

package/src/tools/maintenance.ts

@@ -250,6 +250,22 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
               : {}),
           ...page(pickFields(result.data, FINDING_ROW_FIELDS).map(withFixability), result.nextCursor),
           ...(typeof result.totalCount === 'number' ? { totalCount: result.totalCount } : {}),
+          // The default list has findings with a fix under way too; the sweep's count does not (31 against 33).
+          ...(params.status === undefined &&
+          params.severity === undefined &&
+          params.kind === undefined &&
+          typeof result.totalCount === 'number' &&
+          sweep &&
+          sweep !== 'unread' &&
+          typeof (sweep as Row)['openFindings'] === 'number' &&
+          (sweep as Row)['openFindings'] !== result.totalCount
+            ? {
+                totalNote:
+                  'totalCount includes findings with a fix under way (remediating) and ignored findings whose ' +
+                  'ignore has expired; ' +
+                  'sweep.openFindings counts open ones only.',
+              }
+            : {}),
         });
       })
   );

package/src/tools/repositories.ts

@@ -53,7 +53,7 @@ const GITHUB_REPOSITORY_FIELDS = [
 
 const repositoryId = idInput(
   'repository link',
-  'taiga_list_product_repositories gives it; a GitHub repository id is not one'
+  'taiga_list_product_repositories gives it; a linkable repository id is not one'
 );
 
 /** Round-robin over lists: the first of each, then the second of each, and so on. */
@@ -66,6 +66,34 @@ export function interleave<T>(lists: T[][]): T[] {
   return out;
 }
 
+/**
+ * A repository linked elsewhere names the product that holds it (PRO-2800): the API says "another product", and a
+ * reviewer spent a call finding which. One read, the products the key can see; null leaves the API's refusal.
+ */
+async function holderOf(client: TaigaClient, error: unknown, productId: string) {
+  if (!(error instanceof TaigaApiError) || error.status !== 409) return null;
+  const name = /^(\S+\/\S+) is already linked to another product\.?$/.exec(error.apiMessage ?? '')?.[1];
+  if (!name) return null;
+  try {
+    // The refusal names the repository only, not its host, and the same name can live on github.com and on an
+    // enterprise host: these are the products with a repository of that name, which is as exact as it can say.
+    const holders = (await client.listProducts({ repository: name, limit: 20 })).data.filter((p) => p.id !== productId);
+    const said =
+      holders.length > 0
+        ? `Products this key can see with a repository named ${name}: ${holders.map((p) => `${p.name} (${p.id})`).join(', ')}.`
+        : 'It is linked to a product this key cannot see.';
+    return toolError(
+      'CONFLICT',
+      `${name} is already linked to another product. ${said} A repository belongs to one product; unlink it there ` +
+        'first (taiga_unlink_repository) if this product should have it.',
+      { holders: holders.map((p) => ({ productId: p.id, name: p.name })) }
+    );
+  } catch (inner) {
+    if (inner instanceof TaigaApiError || isNetworkFailure(inner)) return null;
+    throw inner;
+  }
+}
+
 /**
  * A product in setup says what it still needs after a repository write, as create_product and get_product do
  * (PRO-2800): a reviewer had to read the product again to learn that the import came next. Best effort: the write
@@ -132,8 +160,7 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
         title: 'Find a repository to link',
         description:
           "List the repositories the organization's GitHub connection can reach, to link one with " +
-          "taiga_link_repository (it takes the row's id: Taiga's record of the repository, not GitHub's numeric " +
-          'id, and not a link ID). query searches by name; account (login, owner, or ' +
+          "taiga_link_repository (it takes the row's id as linkableRepositoryId). query searches by name; account (login, owner, or " +
           'installationId) reads one account, else rows come from every account in turn. linked: true means a ' +
           'product already links it (taiga_get_product with its URL says which). No connection means GitHub is not ' +
           'connected yet; someone who can install the app does that once, in the web.',
@@ -236,9 +263,11 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
         'history is imported.',
       inputSchema: z.object({
         productId,
-        githubRepositoryId: idInput(
-          'GitHub repository',
-          "taiga_list_linkable_repositories gives it (the row's id, Taiga's record; not GitHub's numeric id)"
+        // Named for the list it comes from: it is Taiga's record of a repository the connection reaches, and three
+        // reviews read githubRepositoryId as GitHub's numeric id (PRO-2800).
+        linkableRepositoryId: idInput(
+          'linkable repository',
+          "taiga_list_linkable_repositories gives it (a row's id; not GitHub's numeric id, not a link ID)"
         ),
         replacesRepositoryId: repositoryId.optional().describe('The link this one replaces'),
       }),
@@ -246,10 +275,17 @@ export function registerRepositoryTools(server: McpServer, client: TaigaClient)
     },
     (params) =>
       runTool(async () => {
-        const linked = await client.linkRepository(params.productId, {
-          githubRepositoryId: params.githubRepositoryId,
-          ...(params.replacesRepositoryId ? { replacesRepositoryId: params.replacesRepositoryId } : {}),
-        });
+        let linked;
+        try {
+          linked = await client.linkRepository(params.productId, {
+            githubRepositoryId: params.linkableRepositoryId,
+            ...(params.replacesRepositoryId ? { replacesRepositoryId: params.replacesRepositoryId } : {}),
+          });
+        } catch (error) {
+          const holder = await holderOf(client, error, params.productId);
+          if (holder) return holder;
+          throw error;
+        }
         return toolResult({
           ...pickFields([linked.data], LINK_FIELDS)[0],
           ...(await readinessAfter(client, params.productId)),

package/src/tools/sections.ts

@@ -13,7 +13,7 @@
 
 import type { CallToolResult } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { isControlId, POLICY_TYPE_BY_CONTROL_PREFIX } from '@taiga/types';
+import { CONTROL_ID_SOURCE, isControlId, POLICY_TYPE_BY_CONTROL_PREFIX } from '@taiga/types';
 import { toolError, toolResult } from './errors.js';
 
 /** A document's section map, keyed by section id: each value a `StoredSection` or (older rows) a bare string. */
@@ -212,6 +212,34 @@ function controlSections(sections: Sections, ids: readonly string[]): Record<str
   return found;
 }
 
+/**
+ * A policy outline names the controls each section states (PRO-2800): a reviewer guessed secretsManagement from its
+ * name, which works for secrets and not for "what covers logging of secret access". Read off each section's text.
+ */
+function withControls(outline: { id: string; characters: number }[], sections: Sections, policyType: unknown) {
+  // The first cell of a control table row, as the API reads a policy's controls (policy-controls.ts CONTROL_ROW):
+  // not AES-256 in prose, nor "see SEC-5.1" in a section that only cites it.
+  // A reserved row (_Reserved_) is a retired id, not a control, as heldControlMap skips it.
+  const pattern = new RegExp(`^\\|\\s*(${CONTROL_ID_SOURCE})\\s*\\|\\s*(.*?)\\s*(?:\\||$)`, 'gm');
+  return outline.map((entry) => {
+    const text = sectionContent(sections, entry.id) ?? '';
+    const ids = [
+      ...new Set(
+        [...text.matchAll(pattern)]
+          .filter((match) => !/^_?Reserved_?/i.test(match[2] ?? ''))
+          .map((match) => match[1]!)
+          // A base control belongs to the policy its prefix names: an SEC row in the data policy is a stale mention,
+          // as heldControlMap reads it. An overlay prefix stays where it is written.
+          .filter((id) => {
+            const owner = POLICY_TYPE_BY_CONTROL_PREFIX[id.split('-')[0] ?? ''];
+            return owner === undefined || owner === policyType;
+          })
+      ),
+    ];
+    return ids.length > 0 ? { ...entry, controls: ids } : entry;
+  });
+}
+
 /**
  * The answer to a read that names sections: the ones the document has, the
  * rest listed with their sizes, and the asked-for ids it lacks under
@@ -254,7 +282,10 @@ export function sectionReadResult(
     const { data: _data, ...meta } = cut.doc;
     return toolResult({
       ...meta,
-      outline: cut.omittedSections,
+      outline:
+        options.controlIds && before
+          ? withControls(cut.omittedSections, before, (doc as { type?: unknown }).type)
+          : cut.omittedSections,
       ...(unknownSections.length > 0 ? { unknownSections } : {}),
       ...controlNote,
     });