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

package/dist/index.js

@@ -2284,7 +2284,8 @@ function withStop(text) {
 */
 const PRODUCT_WORDS = {
 	backlogItemId: "initiativeId",
-	buildRunId: "runId"
+	buildRunId: "runId",
+	latestBuild: "latestRun"
 };
 /**
 * Maps whose keys are content, not API fields: a document's sections are keyed
@@ -2310,6 +2311,10 @@ function inProductWords(value) {
 	});
 	return out;
 }
+/** The API's 404 sentence in the product's words: "Backlog item not found" is an initiative not found. */
+function inProductWording(said) {
+	return said.replace(/^Backlog item not found/i, "Initiative not found").replace(/^Build run step not found/i, "Run step not found").replace(/^Build run not found/i, "Run not found");
+}
 /** A successful tool result: one JSON text block the model reads. */
 function toolResult(value) {
 	return { content: [{
@@ -2390,7 +2395,7 @@ async function runTool(handler) {
 		if (error instanceof TaigaApiError) {
 			const code = error.code ?? CODE_BY_STATUS[error.status] ?? "API_ERROR";
 			const said = error.apiMessage ?? `Taiga API answered ${error.status}.`;
-			return toolError(code, error.status === 404 ? withNotFoundHint(said) : said, error.details);
+			return toolError(code, error.status === 404 ? withNotFoundHint(inProductWording(said)) : said, error.details);
 		}
 		if (isNetworkFailure(error)) return toolError("NETWORK_ERROR", `Could not reach the Taiga API: ${networkFailureDetail(error)}. Check TAIGA_API_URL.`);
 		throw error;
@@ -2581,7 +2586,26 @@ function budgetSections(doc, budget) {
 * The `sections` input of a document read: some sections by id, none for the
 * outline (every id with its size and no text), or omitted for the whole.
 */
-const sectionsInput = z.array(z.string().min(1).max(200)).max(50).optional().describe("Only these sections, by id; [] for the outline (under outline: every section id and its size, no text); omit for the whole document");
+const sectionsInput = z.array(z.string().min(1).max(200)).max(50).optional().describe("Only these sections, by id, or a policy control id (SEC-5.1) for the sections that state it; [] for the outline (under outline: every section id and its size, no text); omit for the whole document");
+/** A policy control id as the standing cites it: SEC-5.1, SDLC-3.1, GDPR-2.3. */
+const CONTROL_ID = /^[A-Z][A-Z0-9]*-\d+(\.\d+)*$/;
+/**
+* The sections that state each control id asked for (PRO-2800): policy
+* standing cites SEC-5.1, and the section holding it has an id of its own
+* (secretsManagement) an agent could only guess. A control id is found in
+* the sections' text, matched as a whole id so SEC-5.1 is not SEC-5.10.
+*/
+function controlSections(sections, ids) {
+	const found = {};
+	for (const id of ids) {
+		if (!CONTROL_ID.test(id) || Object.hasOwn(sections, id)) continue;
+		const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const pattern = new RegExp(`(^|[^A-Za-z0-9.-])${escaped}(?![A-Za-z0-9-]|\\.[A-Za-z0-9])`);
+		const holders = Object.keys(sections).filter((sectionId) => pattern.test(sectionContent(sections, sectionId) ?? ""));
+		if (holders.length > 0) found[id] = holders;
+	}
+	return found;
+}
 /**
 * 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
@@ -2590,12 +2614,17 @@ const sectionsInput = z.array(z.string().min(1).max(200)).max(50).optional().des
 * real id with its size, so the retry needs nothing else. No ids is the
 * outline.
 */
-function sectionReadResult(doc, ids, label) {
+function sectionReadResult(doc, asked, label) {
+	const before = sectionsOf(doc.data);
+	const controls = before ? controlSections(before, asked) : {};
+	const ids = [.../* @__PURE__ */ new Set([...asked.filter((id) => !Object.hasOwn(controls, id)), ...Object.values(controls).flat()])];
 	const cut = pickSections(doc, new Set(ids));
 	if (!cut) return toolError("VALIDATION_ERROR", `The ${label} is not made of sections; read it without sections.`);
 	const all = Object.keys(sectionsOf(doc.data) ?? {});
 	const unknownSections = ids.filter((id) => !all.includes(id));
-	if (ids.filter((id) => all.includes(id)).length === 0) {
+	const known = ids.filter((id) => all.includes(id));
+	const found = Object.keys(controls).length > 0 ? { controls } : {};
+	if (known.length === 0) {
 		const { data: _data, ...meta } = cut.doc;
 		return toolResult({
 			...meta,
@@ -2605,6 +2634,7 @@ function sectionReadResult(doc, ids, label) {
 	}
 	return toolResult({
 		...cut.doc,
+		...found,
 		omittedSections: cut.omittedSections,
 		...unknownSections.length > 0 ? { unknownSections } : {}
 	});
@@ -2628,12 +2658,12 @@ function named(types) {
 	return types.map((type) => PRODUCT_DOCUMENT_NAMES[type] ?? type).join(", ");
 }
 /** The product's setup readiness, or null once it has finished setup. */
-async function setupReadiness(client, product) {
+async function setupReadiness(client, product, links) {
 	if (product["status"] !== "draft") return null;
 	const id = String(product["id"]);
 	const imported = isImportedProduct(product);
 	const [repos, blockers, full] = await Promise.all([
-		client.listProductRepositories(id).then((result) => result.data, (error) => {
+		(links ? links() : client.listProductRepositories(id)).then((result) => result.data, (error) => {
 			if (isApiSide(error)) return null;
 			throw error;
 		}),
@@ -2659,9 +2689,9 @@ async function setupReadiness(client, product) {
 	return {
 		ready: blockers ? missing.length === 0 && openChecks.length === 0 : null,
 		repository,
-		...importState ? { import: importState } : {},
+		...imported ? { import: typeof settings.importStatus === "string" ? settings.importStatus : "pending" } : {},
 		...imported ? {} : { discoveryStep: full["discoveryStep"] ?? null },
-		missingDocuments: missing ? missing.map((type) => named([type])) : null,
+		missingDocuments: missing,
 		openChecks,
 		nextStep: nextStepFor({
 			imported,
@@ -2787,6 +2817,41 @@ const PRODUCT_SUMMARY_FIELDS = [
 	"factoryId",
 	"discoveryStep"
 ];
+/**
+* Product rows with their factory's name beside its id (PRO-2800): "what
+* products does the organization have" needed a second list to name the
+* factories. One factories read; without factories:read, or when it fails,
+* the rows keep the id alone.
+*/
+async function withFactoryNames(client, rows) {
+	if (!client.hasCapability("factories:read") || rows.length === 0) return rows;
+	try {
+		const wanted = new Set(rows.map((row) => String(row.factoryId)));
+		const names = /* @__PURE__ */ new Map();
+		let cursor;
+		for (let pageIndex = 0; pageIndex < FACTORY_PAGES; pageIndex += 1) {
+			const result = await client.listFactories({
+				limit: 100,
+				cursor
+			});
+			for (const factory of result.data) names.set(factory.id, factory.name);
+			if (!result.nextCursor || [...wanted].every((id) => names.has(id))) break;
+			cursor = result.nextCursor;
+		}
+		return rows.map((row) => {
+			const name = names.get(String(row.factoryId));
+			return name === void 0 ? row : {
+				...row,
+				factoryName: name
+			};
+		});
+	} catch (error) {
+		if (error instanceof TaigaApiError || isNetworkFailure(error)) return rows;
+		throw error;
+	}
+}
+/** Factory pages read to name products' factories. */
+const FACTORY_PAGES = 10;
 /** A list's name search: part of a name, any case. */
 const query = (what) => z.string().trim().min(1).max(200).optional().describe(`Part of the ${what}, any case: only the rows that contain it`);
 /**
@@ -2987,7 +3052,7 @@ function registerProductTools(server, client) {
 	if (client.hasCapability("products:read")) {
 		server.registerTool("taiga_list_products", {
 			title: "List products",
-			description: `List products in the organization, as summaries (id, name, slug, status, factory, discoveryStep). Use this to find a product by name (query); inside a git checkout, taiga_resolve_product finds it from the remote URL instead. taiga_get_product reads one in full. ${DISCOVERY_STEP_MEANING}`,
+			description: `List products in the organization, as summaries (id, name, slug, status, factoryId and factoryName, discoveryStep). Use this to find a product by name (query); inside a git checkout, taiga_resolve_product finds it from the remote URL instead. taiga_get_product reads one in full. ${DISCOVERY_STEP_MEANING}`,
 			inputSchema: z.object({
 				query: query("product name or slug"),
 				factoryId: idInput("factory", "taiga_list_factories (query finds one by name) gives it").optional().describe("Only the products of this factory"),
@@ -2999,7 +3064,7 @@ function registerProductTools(server, client) {
 			const { query: text, ...filters } = params;
 			if (text === void 0) {
 				const result = await client.listProducts(filters);
-				return toolResult(page(pickFields(result.data, PRODUCT_SUMMARY_FIELDS), result.nextCursor));
+				return toolResult(page(await withFactoryNames(client, pickFields(result.data, PRODUCT_SUMMARY_FIELDS)), result.nextCursor));
 			}
 			if (params.cursor !== void 0) return toolError("VALIDATION_ERROR", SEARCH_WITH_CURSOR);
 			const found = await searchPages((cursor) => client.listProducts({
@@ -3009,13 +3074,13 @@ function registerProductTools(server, client) {
 				cursor
 			}), text, (row) => [row.name, row.slug], params.limit ?? 25);
 			return toolResult({
-				...page(pickFields(found.rows, PRODUCT_SUMMARY_FIELDS), null),
+				...page(await withFactoryNames(client, pickFields(found.rows, PRODUCT_SUMMARY_FIELDS)), null),
 				...found.more ? { more: SEARCH_NOTE } : {}
 			});
 		}));
 		server.registerTool("taiga_get_product", {
 			title: "Get product",
-			description: "Get one product in full, by ID or by slug: name, slug, factory, what Taiga owns for it (application, infrastructure, deployment) and its settings; the list and resolve tools carry summaries; taiga_get_product_context carries this summary with the rest a session starts from. Use taiga_list_product_documents for its specification and design, taiga_list_initiatives for its work and taiga_list_runs for what the coding agent did. A product still in setup carries readiness: whether it can finish setup now, its repository and import, the required documents not yet published, the checks not yet stamped, and nextStep, the one move that gets it closer.",
+			description: "Read one product record and its settings, by ID or by slug: name, slug, factory, what Taiga owns for it (application, infrastructure, deployment) and its settings; the list and resolve tools carry summaries; taiga_get_product_context carries this summary with the rest a session starts from. Use taiga_list_product_documents for its specification and design, taiga_list_initiatives for its work and taiga_list_runs for what the coding agent did. A product still in setup carries readiness: whether it can finish setup now, its repository and import, the required documents not yet published, the checks not yet stamped, and nextStep, the one move that gets it closer.",
 			inputSchema: z.object({
 				productId: productId.optional(),
 				slug: slug.optional()
@@ -3409,163 +3474,6 @@ function requestPrompt(title, description) {
 	return [(title ?? "").trim(), body].filter(Boolean).join("\n\n") || void 0;
 }
 //#endregion
-//#region src/tools/queue.ts
-/** How many entries the read names; past this an entry keeps its initiativeId only. */
-const NAMED_ENTRIES = 25;
-const MOVE_ASIDE = "or move it down (taiga_queue_initiative with afterId) or off the line (taiga_move_initiative) to let the rest pass.";
-/**
-* What lifts a halt, in the tools that do it. Read from the halt registry in
-* @taiga/types (how each cause clears, and whether a person may lift it), so
-* the advice cannot drift from what the API accepts; plan review is the one
-* cause a tool answers directly.
-*/
-function haltNextStep(cause) {
-	if (cause === "awaiting_plan_review") return "Read the plan with taiga_get_plan, then approve it (taiga_approve_plan) or send it back (taiga_reject_plan).";
-	const spec = cause ? HALT_CAUSES[cause] : void 0;
-	if (!cause || !spec) return `Read the initiative with taiga_get_initiative to see why, ${MOVE_ASIDE}`;
-	const known = cause;
-	if (canResumeHalt(known)) return `taiga_resume_initiative lifts it, ${MOVE_ASIDE}`;
-	if (haltClearsItself(known)) return `It clears when ${spec.clearedWhen}; ${MOVE_ASIDE}`;
-	return `Only taking it off the line clears it (taiga_move_initiative): ${spec.clearedWhen}.`;
-}
-/**
-* The entry the line waits on, by the queue's two kinds of blocker
-* (@taiga/types): an active entry holds every other one wherever it sits, so
-* it answers first; without one, the first halted entry holds the entries
-* behind it. -1 when neither is there.
-*/
-function blockingIndex(entries, stateOf) {
-	const active = entries.findIndex((entry) => stateOf(entry) === "active");
-	return active >= 0 ? active : entries.findIndex((entry) => stateOf(entry) === "halted");
-}
-/** The one sentence a person needs: what the line is doing, or what it is waiting on. */
-function waitingOn(rows) {
-	const at = blockingIndex(rows, (row) => row.entryState);
-	if (at < 0) return rows.length > 0 ? "Nothing in the queue is running; the first queued initiative starts when the line is free." : null;
-	const head = rows[at];
-	const name = typeof head.title === "string" ? `"${head.title}"` : `Initiative ${String(head.backlogItemId)}`;
-	if (head.entryState === "halted") {
-		const halt = head.halt;
-		const ahead = at > 0 ? " Entries ahead of it are not held by it." : "";
-		return `${name} halted the queue, holding the entries behind it: ${halt.reason} ${halt.nextStep}${ahead}`;
-	}
-	const lifecycle = head.lifecycle;
-	const held = "every other queued initiative waits until its pull request merges.";
-	if (!lifecycle) return `${name} is the active entry; ${held}`;
-	const pr = typeof head.prUrl === "string" ? ` (${head.prUrl})` : "";
-	if (lifecycle.cta === "start_build") return `${name} has its plan and waits for the Build slot; ${held}`;
-	if (lifecycle.turn === "you") return `${name} is waiting on a person (${String(lifecycle.cta ?? lifecycle.stage)})${pr}; ${held}`;
-	return `${name} is ${String(lifecycle.stage)}${pr}; ${held}`;
-}
-/**
-* The product's queue as a person reads it: each live entry in order with its
-* initiative's title and where that initiative is, a halted entry with why and
-* what lifts it, and one sentence saying what the line is waiting on. The
-* route carries item ids only; each is named by one item read (when the key
-* may read the backlog), and a read the API fails leaves that entry unnamed
-* rather than failing the queue.
-*/
-async function queueView(client, product, options = { name: "all" }) {
-	const [queue, paused] = await Promise.all([client.listQueue(product), linePausedSince(client, product)]);
-	const entries = queue.data.filter((entry) => entry.state !== "settled");
-	const canName = client.hasCapability("backlog:read");
-	const blocking = blockingIndex(entries, (entry) => entry.state);
-	const toName = !canName ? [] : options.name === "all" ? entries.slice(0, NAMED_ENTRIES).map((_, index) => index) : blocking >= 0 ? [blocking] : [];
-	const settled = await Promise.allSettled(toName.map((index) => client.getBacklogItem(entries[index].backlogItemId)));
-	const reads = new Map(toName.map((index, at) => [index, settled[at]]));
-	let unnamed = options.name === "all" ? entries.length - toName.length : 0;
-	const rows = entries.map((entry, index) => {
-		const read = reads.get(index);
-		if (read?.status === "rejected") {
-			if (!(read.reason instanceof TaigaApiError || isNetworkFailure(read.reason))) throw read.reason;
-			unnamed += 1;
-		}
-		const item = read?.status === "fulfilled" ? read.value.data : null;
-		const lifecycle = item?.lifecycle;
-		const latestBuild = lifecycle?.latestBuild;
-		const row = {
-			position: index + 1,
-			backlogItemId: entry.backlogItemId,
-			entryState: entry.state
-		};
-		if (item) Object.assign(row, {
-			title: item.title,
-			state: item.state,
-			planningStatus: item.planningStatus,
-			needsHumanCause: item.needsHumanCause,
-			criteria: criteriaCounts(item),
-			lifecycle: lifecycle ? {
-				turn: lifecycle.turn,
-				stage: lifecycle.stage,
-				cta: lifecycle.cta
-			} : null,
-			...latestBuild ? {
-				runId: latestBuild.id,
-				prUrl: latestBuild.prUrl ?? null
-			} : {}
-		});
-		if (entry.state === "halted") {
-			const cause = typeof entry.haltCause === "string" ? entry.haltCause : null;
-			row.halt = {
-				cause,
-				reason: (cause ? renderHalt({
-					cause,
-					params: entry.haltParams ?? {}
-				}) : "") || (typeof entry.haltReason === "string" ? entry.haltReason : "The queue stopped here."),
-				nextStep: haltNextStep(cause)
-			};
-		}
-		return row;
-	});
-	const note = unnamed === 0 ? null : !canName ? "Entries carry initiativeId only: naming them needs backlog:read, which this key lacks." : entries.length > NAMED_ENTRIES ? `Only the first ${NAMED_ENTRIES} entries are named; the rest carry initiativeId only.` : "An entry whose initiative could not be read carries initiativeId only; taiga_get_initiative reads it.";
-	const line = typeof paused === "string" ? `The line is paused (since ${paused}): nothing is planned or built until a person resumes it.` : null;
-	return {
-		linePaused: paused === null ? null : typeof paused === "string",
-		entries: rows,
-		waitingOn: line ?? waitingOn(rows),
-		...note ? { note } : {}
-	};
-}
-/**
-* When the product's line was paused, false when it runs, null when the
-* product cannot be read (the queue is still worth reading without it).
-*/
-async function linePausedSince(client, product) {
-	try {
-		const row = (await client.getProduct(product)).data;
-		return typeof row.lineStoppedAt === "string" ? row.lineStoppedAt : false;
-	} catch (error) {
-		if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
-		throw error;
-	}
-}
-function registerQueueTools(server, client) {
-	if (!client.hasCapability("products:read")) return;
-	server.registerTool("taiga_get_line", {
-		title: "Get the product queue",
-		description: "Read a product's queue, the line the coding agent works one initiative at a time: each entry in order with its title, where it is (planning, building, in review) and whose turn it is, a halted entry with why it stopped and what lifts it, linePaused (null when the product could not be read), and waitingOn, one sentence saying what the line is waiting for. The line advances only when the active entry's pull request merges, so an entry waiting on a review holds everything behind it. Use this when a queued initiative is not moving.",
-		inputSchema: z.object({ productId }),
-		annotations: READ_ONLY
-	}, (params) => runTool(async () => toolResult(await queueView(client, params.productId))));
-	if (!client.hasCapability("products:write")) return;
-	server.registerTool("taiga_pause_line", {
-		title: "Pause or resume a product's line",
-		description: "Pause the product's whole line, or resume it. Pausing cancels the plan being written and stops the build in flight where it stands (both are flagged), and nothing more is planned or built; initiatives keep their places. Resuming plans the interrupted initiative again from scratch, carries the interrupted build on from its first incomplete step, and the line picks up where it was; a build you had stopped yourself before pausing stays stopped. Idempotent. Pausing interrupts work and resuming starts it: read taiga_get_line first to see what it would interrupt, and ask the person.",
-		inputSchema: z.object({
-			productId,
-			paused: z.boolean().describe("true pauses the line, false resumes it")
-		}),
-		annotations: OPERATE_SETTING
-	}, (params) => runTool(async () => {
-		const row = (await client.setLineStopped(params.productId, params.paused)).data;
-		return toolResult({
-			productId: row.id,
-			linePaused: typeof row.lineStoppedAt === "string",
-			lineStoppedAt: row.lineStoppedAt ?? null
-		});
-	}));
-}
-//#endregion
 //#region src/tools/builds.ts
 /** What a list row needs to say for the model to pick a run to read in full. */
 const BUILD_SUMMARY_FIELDS = [
@@ -3588,6 +3496,8 @@ const BUILD_SUMMARY_FIELDS = [
 	"prState",
 	"prDraft",
 	"prMerged",
+	"reviewEscalation",
+	"error",
 	"actions",
 	"createdAt",
 	"startedAt",
@@ -3604,7 +3514,10 @@ const RUN_OUTCOME_FIELDS = [
 	"totalSteps",
 	"prNumber",
 	"prUrl",
+	"prDraft",
 	"prMerged",
+	"reviewEscalation",
+	"error",
 	"actions"
 ];
 /**
@@ -3642,6 +3555,46 @@ const RUNNING = {
 	ci_fixing: "fixing what CI found",
 	reviewing: "answering review comments on the pull request"
 };
+/** Why the agent handed a run back, in the web's words (apps/web handback), with the checks it names. */
+function handbackSaid(escalation) {
+	if (!escalation || typeof escalation !== "object") return null;
+	const e = escalation;
+	const checks = Array.isArray(e.failingChecks) ? e.failingChecks.map((check) => String(check.name)).join(", ") : "";
+	const on = checks ? ` on ${checks}` : "";
+	const rounds = typeof e.rounds === "number" && e.rounds > 0 ? ` after ${e.rounds} automatic round${e.rounds === 1 ? "" : "s"}` : "";
+	const blockers = Array.isArray(e.blockers) ? e.blockers.map((b) => READY_BLOCKER_SAID[String(b)] ?? String(b)) : [];
+	switch (e.reason) {
+		case "ci_fix_cap": return `CI is still failing${on}${rounds}`;
+		case "ci_fix_stalled": return `CI is still failing${on}, and the last fix round changed nothing`;
+		case "conflict_cap": return `the branch still conflicts with its base${rounds}`;
+		case "review_bot_cap": return `review bots still have open comments${rounds}`;
+		case "ci_never_settled": return "CI did not finish in time";
+		case "ready_blocked": return `CI is green, but Taiga kept the pull request a draft${blockers.length ? `: ${blockers.join("; ")}` : ""}`;
+		case "check_weakened": return `CI went green only after a check was loosened${typeof e.file === "string" ? ` in ${e.file}` : ""}`;
+		default: return typeof e.reason === "string" ? e.reason : null;
+	}
+}
+/** What a person does about a handback, by its reason, as the web's handback detail says it. */
+function handbackNextStep(escalation) {
+	const reason = escalation && typeof escalation === "object" ? escalation.reason : null;
+	if (reason === "check_weakened") return "review the loosened check before merging, or review it back to the agent";
+	if (reason === "ci_never_settled") return "look at what is still running or queued in CI, then review it back to the agent";
+	return "fix it by hand or review it back to the agent";
+}
+/** The web's words for why Taiga keeps a pull request a draft. */
+const READY_BLOCKER_SAID = {
+	plan_incomplete: "not every planned step shipped",
+	tests_failed: "the tests Taiga ran after the build failed",
+	bar_lowering: "a fix lowered a check instead of fixing the code",
+	bar_lowering_unchecked: "Taiga could not check whether a fix lowered a check",
+	criticals_unresolved: "Taiga's own review left a critical issue unresolved"
+};
+/** The first sentence of a run's error, short enough for a row. */
+function errorSaid(error) {
+	if (typeof error !== "string" || !error.trim()) return null;
+	const first = error.trim().split(/\n|(?<=[.!?])\s/)[0].replace(/[.!?]$/, "");
+	return first.length > 240 ? `${first.slice(0, 240).trimEnd()}...` : first;
+}
 /**
 * How a run stands, in one sentence, with its disposition: the meaning the
 * status and the pull request facts carry between them
@@ -3655,34 +3608,41 @@ function runOutcome(run) {
 	const disposition = landedDisposition(status, run["prMerged"] === true);
 	const pr = typeof run["prNumber"] === "number" ? `PR #${run["prNumber"]}` : "its pull request";
 	const progress = typeof run["completedSteps"] === "number" && typeof run["totalSteps"] === "number" ? ` (${run["completedSteps"]} of ${run["totalSteps"]} steps done)` : "";
-	const reason = typeof run["failedReason"] === "string" && run["failedReason"] ? `: ${run["failedReason"]}` : "";
+	const why = errorSaid(run["error"]) ?? (typeof run["failedReason"] === "string" ? run["failedReason"] : null);
+	const handback = handbackSaid(run["reviewEscalation"]);
+	const draft = run["prDraft"] === true ? `, still a draft` : "";
 	return {
 		disposition,
 		outcome: {
 			in_flight: status === "pending" ? "Queued: waiting to start." : `Running: ${RUNNING[status] ?? status}${progress}.`,
-			gated: `Waiting for a person to review and merge ${pr}.`,
+			gated: handback ? `Handed back to a person: ${handback}. ${pr}${draft ? `${draft},` : ""} waits for them to ${handbackNextStep(run["reviewEscalation"])}.` : `Waiting for a person to review and merge ${pr}${draft}.`,
 			succeeded: `Merged: ${pr} is in ${typeof run["baseBranch"] === "string" ? run["baseBranch"] : "the base branch"}.`,
 			unmerged: typeof run["prNumber"] === "number" || run["prUrl"] ? `Settled without merging: ${pr} was left unmerged.` : "Settled without a merged pull request.",
-			failed: `Failed${reason}${progress}.`,
+			failed: `Failed${why ? `: ${why}` : ""}${progress}.`,
 			stopped: `Stopped before it finished${progress}.`,
-			rejected: `${pr} was closed without merging, so the work did not land.`
+			rejected: `${pr} was closed without merging, so the work did not land.${handback ? ` It had been handed back: ${handback}.` : ""}`
 		}[disposition] ?? status
 	};
 }
 /**
 * A run row as an agent reads it: its outcome added, and prDraft only where
 * there is a pull request. The column defaults to true, so a run that never
-* opened one said it had a draft (PRO-2800).
+* opened one said it had a draft (PRO-2800). A list row leaves the full error
+* text out: its first sentence is in the outcome, and taiga_get_run has it all.
 */
-function readableRun(run) {
-	const { prDraft, ...rest } = run;
+function readableRun(run, opts = {}) {
+	const { prDraft, error, reviewEscalation, ...rest } = run;
 	const said = runOutcome(run);
 	return {
 		...rest,
+		...opts.row || error === void 0 ? {} : { error },
+		...opts.row || reviewEscalation === void 0 ? {} : { reviewEscalation },
 		...typeof rest["prNumber"] === "number" || rest["prUrl"] ? { prDraft } : {},
 		...said ?? {}
 	};
 }
+/** readableRun for a list row. */
+const readableRow = (run) => readableRun(run, { row: true });
 /** How many products the org-wide list names; past this a row keeps its productId only. */
 const NAMED_PRODUCTS = 100;
 const runId = idInput("run", "taiga_list_runs gives it");
@@ -3726,7 +3686,7 @@ async function activityRows(client, opts) {
 		name: product.name,
 		slug: product.slug
 	});
-	const rows = pickFields(runs.data, BUILD_SUMMARY_FIELDS).map(readableRun).map((row) => {
+	const rows = pickFields(runs.data, BUILD_SUMMARY_FIELDS).map(readableRow).map((row) => {
 		const product = nameById.get(String(row["productId"]));
 		return product ? {
 			...row,
@@ -3760,13 +3720,13 @@ function registerBuildTools(server, client) {
 				limit: params.limit,
 				cursor: params.cursor
 			});
-			return toolResult(page(pickFields(result.data, BUILD_SUMMARY_FIELDS).map(readableRun), result.nextCursor));
+			return toolResult(page(pickFields(result.data, BUILD_SUMMARY_FIELDS).map(readableRow), result.nextCursor));
 		}
 		return toolResult(await activityRows(client, params));
 	}));
 	server.registerTool("taiga_get_run", {
 		title: "Get run",
-		description: "Get one run with its steps: how it stands (outcome, disposition), its pull request and hardening, and each step's title, status, commit, files changed, verification and headline, the first paragraph of what the agent reported. A step's verification is Taiga's own check after the step (tests, lint, build), independent of what the agent says it ran: a docs-only step can show tests failed because the repository's tests fail. A run that failed or was stopped says where (stoppedIn) and when it last made progress (lastProgressAt). Pass full: true for each step's complete instructions and report, several thousand tokens on a long run. Its actions name what the initiative accepts: resume and retry_from_failed_step are taiga_resume_initiative; start_over is in the 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: how it stands (outcome, disposition), its pull request and hardening, and each step's title, status, commit, files changed, verification and headline, the first paragraph of what the agent reported. A step's verification is Taiga's own check after the step (tests, lint, build), independent of what the agent says it ran: a docs-only step can show tests failed because the repository's tests fail. A run that failed or was stopped says where (stoppedIn) and when it last made progress (lastProgressAt). Pass full: true for each step's complete instructions and report, several thousand tokens on a long run. Its actions name what the initiative accepts: resume and retry_from_failed_step are taiga_resume_initiative; start_over is in the web only; 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)")
@@ -3799,7 +3759,170 @@ function registerBuildTools(server, client) {
 		inputSchema: z.object({ runId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
-		return toolResult(readableRun(pickFields([(await client.stopBuildRun(params.runId)).data], RUN_OUTCOME_FIELDS)[0]));
+		const result = await client.stopBuildRun(params.runId);
+		return toolResult(readableRow(pickFields([result.data], RUN_OUTCOME_FIELDS)[0]));
+	}));
+}
+//#endregion
+//#region src/tools/queue.ts
+/** How many entries the read names; past this an entry keeps its initiativeId only. */
+const NAMED_ENTRIES = 25;
+const MOVE_ASIDE = "or move it down (taiga_queue_initiative with afterId) or off the line (taiga_move_initiative) to let the rest pass.";
+/**
+* What lifts a halt, in the tools that do it. Read from the halt registry in
+* @taiga/types (how each cause clears, and whether a person may lift it), so
+* the advice cannot drift from what the API accepts; plan review is the one
+* cause a tool answers directly.
+*/
+function haltNextStep(cause) {
+	if (cause === "awaiting_plan_review") return "Read the plan with taiga_get_plan, then approve it (taiga_approve_plan) or send it back (taiga_reject_plan).";
+	const spec = cause ? HALT_CAUSES[cause] : void 0;
+	if (!cause || !spec) return `Read the initiative with taiga_get_initiative to see why, ${MOVE_ASIDE}`;
+	const known = cause;
+	if (canResumeHalt(known)) return `taiga_resume_initiative lifts it, ${MOVE_ASIDE}`;
+	if (haltClearsItself(known)) return `It clears when ${spec.clearedWhen}; ${MOVE_ASIDE}`;
+	return `Only taking it off the line clears it (taiga_move_initiative): ${spec.clearedWhen}.`;
+}
+/**
+* The entry the line waits on, by the queue's two kinds of blocker
+* (@taiga/types): an active entry holds every other one wherever it sits, so
+* it answers first; without one, the first halted entry holds the entries
+* behind it. -1 when neither is there.
+*/
+function blockingIndex(entries, stateOf) {
+	const active = entries.findIndex((entry) => stateOf(entry) === "active");
+	return active >= 0 ? active : entries.findIndex((entry) => stateOf(entry) === "halted");
+}
+/** The one sentence a person needs: what the line is doing, or what it is waiting on. */
+function waitingOn(rows) {
+	const at = blockingIndex(rows, (row) => row.entryState);
+	if (at < 0) return rows.length > 0 ? "Nothing in the queue is running; the first queued initiative starts when the line is free." : null;
+	const head = rows[at];
+	const name = typeof head.title === "string" ? `"${head.title}"` : `Initiative ${String(head.backlogItemId)}`;
+	if (head.entryState === "halted") {
+		const halt = head.halt;
+		const ahead = at > 0 ? " Entries ahead of it are not held by it." : "";
+		return `${name} halted the queue, holding the entries behind it: ${halt.reason} ${halt.nextStep}${ahead}`;
+	}
+	const lifecycle = head.lifecycle;
+	const held = "every other queued initiative waits until its pull request merges.";
+	if (!lifecycle) return `${name} is the active entry; ${held}`;
+	const pr = typeof head.prUrl === "string" ? ` (${head.prUrl})` : "";
+	if (lifecycle.cta === "start_build") return `${name} has its plan and waits for the Build slot; ${held}`;
+	if (head.handedBack) return `${name} was handed back to a person: ${head.handedBack}${pr}; ${held}`;
+	if (lifecycle.turn === "you") return `${name} is waiting on a person (${String(lifecycle.cta ?? lifecycle.stage)})${pr}; ${held}`;
+	return `${name} is ${String(lifecycle.stage)}${pr}; ${held}`;
+}
+/**
+* The product's queue as a person reads it: each live entry in order with its
+* initiative's title and where that initiative is, a halted entry with why and
+* what lifts it, and one sentence saying what the line is waiting on. The
+* route carries item ids only; each is named by one item read (when the key
+* may read the backlog), and a read the API fails leaves that entry unnamed
+* rather than failing the queue.
+*/
+async function queueView(client, product, options = { name: "all" }) {
+	const [queue, paused] = await Promise.all([client.listQueue(product), linePausedSince(client, product)]);
+	const entries = queue.data.filter((entry) => entry.state !== "settled");
+	const canName = client.hasCapability("backlog:read");
+	const blocking = blockingIndex(entries, (entry) => entry.state);
+	const toName = !canName ? [] : options.name === "all" ? entries.slice(0, NAMED_ENTRIES).map((_, index) => index) : blocking >= 0 ? [blocking] : [];
+	const settled = await Promise.allSettled(toName.map((index) => client.getBacklogItem(entries[index].backlogItemId)));
+	const reads = new Map(toName.map((index, at) => [index, settled[at]]));
+	let unnamed = options.name === "all" ? entries.length - toName.length : 0;
+	const rows = entries.map((entry, index) => {
+		const read = reads.get(index);
+		if (read?.status === "rejected") {
+			if (!(read.reason instanceof TaigaApiError || isNetworkFailure(read.reason))) throw read.reason;
+			unnamed += 1;
+		}
+		const item = read?.status === "fulfilled" ? read.value.data : null;
+		const lifecycle = item?.lifecycle;
+		const latestBuild = lifecycle?.latestBuild;
+		const row = {
+			position: index + 1,
+			backlogItemId: entry.backlogItemId,
+			entryState: entry.state
+		};
+		if (item) {
+			Object.assign(row, {
+				title: item.title,
+				state: item.state,
+				planningStatus: item.planningStatus,
+				needsHumanCause: item.needsHumanCause,
+				criteria: criteriaCounts(item),
+				lifecycle: lifecycle ? {
+					turn: lifecycle.turn,
+					stage: lifecycle.stage,
+					cta: lifecycle.cta
+				} : null,
+				...latestBuild ? {
+					runId: latestBuild.id,
+					prUrl: latestBuild.prUrl ?? null
+				} : {}
+			});
+			const handback = handbackSaid(latestBuild?.reviewEscalation);
+			if (handback) row.handedBack = handback;
+		}
+		if (entry.state === "halted") {
+			const cause = typeof entry.haltCause === "string" ? entry.haltCause : null;
+			row.halt = {
+				cause,
+				reason: (cause ? renderHalt({
+					cause,
+					params: entry.haltParams ?? {}
+				}) : "") || (typeof entry.haltReason === "string" ? entry.haltReason : "The queue stopped here."),
+				nextStep: haltNextStep(cause)
+			};
+		}
+		return row;
+	});
+	const note = unnamed === 0 ? null : !canName ? "Entries carry initiativeId only: naming them needs backlog:read, which this key lacks." : entries.length > NAMED_ENTRIES ? `Only the first ${NAMED_ENTRIES} entries are named; the rest carry initiativeId only.` : "An entry whose initiative could not be read carries initiativeId only; taiga_get_initiative reads it.";
+	const line = typeof paused === "string" ? `The line is paused (since ${paused}): nothing is planned or built until a person resumes it.` : null;
+	return {
+		linePaused: paused === null ? null : typeof paused === "string",
+		entries: rows,
+		waitingOn: line ?? waitingOn(rows),
+		...note ? { note } : {}
+	};
+}
+/**
+* When the product's line was paused, false when it runs, null when the
+* product cannot be read (the queue is still worth reading without it).
+*/
+async function linePausedSince(client, product) {
+	try {
+		const row = (await client.getProduct(product)).data;
+		return typeof row.lineStoppedAt === "string" ? row.lineStoppedAt : false;
+	} catch (error) {
+		if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
+		throw error;
+	}
+}
+function registerQueueTools(server, client) {
+	if (!client.hasCapability("products:read")) return;
+	server.registerTool("taiga_get_line", {
+		title: "Get the product queue",
+		description: "Read a product's line, the queue the coding agent works one initiative at a time, and what it waits on: each entry in order with its title, where it is (planning, building, in review) and whose turn it is, a halted entry with why it stopped and what lifts it, linePaused (null when the product could not be read), and waitingOn, one sentence saying what the line is waiting for. The line advances only when the active entry's pull request merges, so an entry waiting on a review holds everything behind it. Use this when a queued initiative is not moving.",
+		inputSchema: z.object({ productId }),
+		annotations: READ_ONLY
+	}, (params) => runTool(async () => toolResult(await queueView(client, params.productId))));
+	if (!client.hasCapability("products:write")) return;
+	server.registerTool("taiga_pause_line", {
+		title: "Pause or resume a product's line",
+		description: "Pause the product's whole line, or resume it. Pausing cancels the plan being written and stops the build in flight where it stands (both are flagged), and nothing more is planned or built; initiatives keep their places. Resuming plans the interrupted initiative again from scratch, carries the interrupted build on from its first incomplete step, and the line picks up where it was; a build you had stopped yourself before pausing stays stopped. Idempotent. Pausing interrupts work and resuming starts it: read taiga_get_line first to see what it would interrupt, and ask the person.",
+		inputSchema: z.object({
+			productId,
+			paused: z.boolean().describe("true pauses the line, false resumes it")
+		}),
+		annotations: OPERATE_SETTING
+	}, (params) => runTool(async () => {
+		const row = (await client.setLineStopped(params.productId, params.paused)).data;
+		return toolResult({
+			productId: row.id,
+			linePaused: typeof row.lineStoppedAt === "string",
+			lineStoppedAt: row.lineStoppedAt ?? null
+		});
 	}));
 }
 //#endregion
@@ -3886,6 +4009,8 @@ function situationOf(item) {
 		const pr = typeof build.prNumber === "number" ? ` (PR #${build.prNumber})` : "";
 		const said = BUILD_RUN_STATUSES.includes(build.status) ? RUN_STANDS[landedDisposition(build.status, build.prMerged === true)] : build.status;
 		stage += `; its latest run ${said}${pr}`;
+		const handback = handbackSaid(build.reviewEscalation);
+		if (handback) stage += `, handed back because ${handback}`;
 	}
 	parts.push(`${stage}.`);
 	if (typeof item["needsHumanCause"] === "string") {
@@ -3896,7 +4021,8 @@ function situationOf(item) {
 		if (why) parts.push(`The line stopped on it: ${why}.`);
 	}
 	const turn = life.turn === "you" ? "A person's turn" : life.turn === "agent" ? "The agent's turn" : null;
-	const move = typeof life.cta === "string" ? CTA_MOVE[life.cta] : void 0;
+	const handedBack = handbackSaid(build?.reviewEscalation);
+	const move = life.cta === "review_pr" && handedBack ? `a person should ${handbackNextStep(build.reviewEscalation)}` : typeof life.cta === "string" ? CTA_MOVE[life.cta] : void 0;
 	if (life.cta === "view_pr") parts.push(`Nothing to do: ${move}.`);
 	else if (turn && move) parts.push(`${turn}: ${move}.`);
 	else if (turn) parts.push(`${turn}.`);
@@ -4018,7 +4144,7 @@ function registerBacklogTools(server, client) {
 function registerBacklogReads(server, client) {
 	server.registerTool("taiga_list_initiatives", {
 		title: "List initiatives",
-		description: "List a product's initiatives, its backlog: titles, category, status, where each one is on the line (backlog, todo, queue, plan, build, done), situation (where it stands and what moves it on, in a sentence) and criteria, how many of its acceptance criteria are met (null before it is planned; met counts the criteria the agent confirmed with evidence or a person checked off, so a done item can show fewer met than it has). Use this to find the item you are working on (query finds one by title), then read its acceptance criteria and technical context with taiga_get_initiative. Archived items are left out unless asked for.",
+		description: "List a product's initiatives (its backlog): titles, category, status, where each one is on the line (backlog, todo, queue, plan, build, done), situation (where it stands and what moves it on, in a sentence) and criteria, how many of its acceptance criteria are met (null before it is planned; met counts the criteria the agent confirmed with evidence or a person checked off, so a done item can show fewer met than it has). Use this to find the item you are working on (query finds one by title), then read its acceptance criteria and technical context with taiga_get_initiative. Archived items are left out unless asked for.",
 		inputSchema: z.object({
 			productId,
 			query: z.string().trim().min(1).max(200).optional().describe("Part of the title, any case: only the items that contain it"),
@@ -4119,7 +4245,7 @@ function registerRequest(server, client) {
 function registerMove(server, client) {
 	server.registerTool("taiga_move_initiative", {
 		title: "Move initiative on the board",
-		description: `Move an initiative on the board, or order it within a column: backlog and todo are yours and the line never moves an initiative out of them; queue puts it in the line (taiga_queue_initiative says more); done and canceled finish it by hand. The queue is the only way to start work: there is no "plan this now", and nothing is moved into Build by a person. Moving an initiative out of Build stops the plan being written or the run in flight: that is how work is stopped, and it throws that work away. A move to ${PR_CLOSING_STATES.join(", ")} CLOSES a pull request the initiative is still waiting on (a move to queue keeps it, and done leaves it to be merged); Taiga leaves a comment on the pull request saying why. The state machine refuses a move that is not allowed (CONFLICT). A move into queue starts paid work and needs products:write. Ask the person before a move that starts work, stops work or closes a pull request. archived: true files the initiative where it stands (pass its current column as state; never from the Build station, plan or build) and archived: false brings it back; archived work is left out of lists unless includeArchived asks for it.`,
+		description: `Move an initiative on the board, take it off the line, or order it within a column: backlog and todo are yours and the line never moves an initiative out of them; queue puts it in the line (taiga_queue_initiative says more); done and canceled finish it by hand. The queue is the only way to start work: there is no "plan this now", and nothing is moved into Build by a person. Moving an initiative out of Build stops the plan being written or the run in flight: that is how work is stopped, and it throws that work away. A move to ${PR_CLOSING_STATES.join(", ")} CLOSES a pull request the initiative is still waiting on (a move to queue keeps it, and done leaves it to be merged); Taiga leaves a comment on the pull request saying why. The state machine refuses a move that is not allowed (CONFLICT). A move into queue starts paid work and needs products:write. Ask the person before a move that starts work, stops work or closes a pull request. archived: true files the initiative where it stands (pass its current column as state; never from the Build station, plan or build) and archived: false brings it back; archived work is left out of lists unless includeArchived asks for it.`,
 		inputSchema: z.object({
 			initiativeId,
 			state: z.enum(USER_DROP_STATES).describe("The column to move into"),
@@ -4242,7 +4368,7 @@ function registerReviewGate(server, client) {
 function registerResume(server, client) {
 	server.registerTool("taiga_resume_initiative", {
 		title: "Resume initiative",
-		description: "Resume an initiative the line stopped on, which is when needsHumanCause is set (the line sets it): a failed or cancelled plan is planned again, a stopped or failed run resumes from its first unfinished part (the steps already committed are kept), a refused build start is cleared and retried. This is the way to carry work on: a run is the record of an attempt, and decisions about the work are made on the initiative. Refused (CONFLICT) when nothing is flagged or the cause has no resume: a plan that failed with needsHumanCause null (lifecycle.cta retry_plan, planFailureCause says why) is planned again with taiga_plan_again. Starts paid work.",
+		description: "Carry on an initiative the line stopped on, which is when needsHumanCause is set (the line sets it): a failed or cancelled plan is planned again, a stopped or failed run resumes from its first unfinished part (the steps already committed are kept), a refused build start is cleared and retried. This is the way to carry work on: a run is the record of an attempt, and decisions about the work are made on the initiative. Refused (CONFLICT) when nothing is flagged or the cause has no resume: a plan that failed with needsHumanCause null (lifecycle.cta retry_plan, planFailureCause says why) is planned again with taiga_plan_again. Starts paid work.",
 		inputSchema: z.object({ initiativeId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => outcome((await client.resumeInitiative(params.initiativeId)).data)));
@@ -4341,6 +4467,8 @@ function standingSummary(standing) {
 	}
 	return {
 		controls: listed.length,
+		controlsInPolicies: controls.length,
+		controlsWithNothingRecorded: controls.length - listed.length,
 		violations: violations.length,
 		bySeverity,
 		resolvedViolations: resolved
@@ -4385,7 +4513,7 @@ function registerMaintenanceTools(server, client) {
 	}));
 	server.registerTool("taiga_get_finding", {
 		title: "Get a maintenance finding",
-		description: "Read one finding in full: what it is, how likely it is to be exploited (EPSS, the known-exploited list), the advisory and the fixed version, the place in the code, the policy controls it breaches, why it is ranked where it is, its history (reintroduced, previously resolved) and the remediation under way. A secret's value is never stored; the finding names the rule and the location only.",
+		description: "Read one maintenance finding in full: what it is, how likely it is to be exploited (EPSS, the known-exploited list), the advisory and the fixed version, the place in the code, the policy controls it breaches, why it is ranked where it is, its history (reintroduced, previously resolved) and the remediation under way. A secret's value is never stored; the finding names the rule and the location only.",
 		inputSchema: z.object({ findingId }),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
@@ -4397,7 +4525,7 @@ function registerMaintenanceTools(server, client) {
 	}));
 	server.registerTool("taiga_get_policy_standing", {
 		title: "Get a product's policy standing",
-		description: "Where a product stands against the organization's own published policies: the controls it violates, each with its violations (critical and high only, each citing the policy's sentence and the document passage that contradicts it), what is being done about each (an initiative raised, a fix in progress, awaiting verification), and when the documents were derived and assessed, led by a summary of the counts. A control is breached when open scanner findings map to it, diverged when the assessment of the product documents found them contradicting it (a control can be both; state names the stronger, breached). A violation's work is the initiative raised for it; live: false means that initiative is done or canceled without the violation going away, so it needs a person or a new fix. A control breached by scanner findings counts them by tier (findingsByTier): a breach of routine findings only, such as secrets in test fixtures, is not an urgent one. A control with no violation is not listed, and it is not \"passing\" either: there is no such state. Pass full: true for every violation's evidence and the resolved ones. Fix a control with taiga_fix_policy_violation.",
+		description: "How a product stands against the organization's own published policies: the controls it violates, each with its violations (critical and high only, each citing the policy's sentence and the document passage that contradicts it), what is being done about each (an initiative raised, a fix in progress, awaiting verification), and when the documents were derived and assessed, led by a summary of the counts. A control is breached when open scanner findings map to it, diverged when the assessment of the product documents found them contradicting it (a control can be both; state names the stronger, breached). A violation's work is the initiative raised for it; live: false means that initiative is done or canceled without the violation going away, so it needs a person or a new fix. A control breached by scanner findings counts them by tier (findingsByTier): a breach of routine findings only, such as secrets in test fixtures, is not an urgent one. A control with no violation is not listed, and it is not \"passing\" either: there is no such state; summary.controlsWithNothingRecorded counts them. Pass full: true for every violation's evidence and the resolved ones. Fix a control with taiga_fix_policy_violation.",
 		inputSchema: z.object({
 			productId,
 			full: z.boolean().optional().describe("Carry each violation's evidence, the policy excerpt and the resolved violations (default false)")
@@ -4409,12 +4537,15 @@ function registerMaintenanceTools(server, client) {
 		const violations = Array.isArray(standing.divergences) ? standing.divergences : [];
 		const listed = controls.filter((c) => Number(c.divergenceCount ?? 0) > 0 || Number(c.findingCount ?? 0) > 0);
 		const summary = standingSummary(standing);
+		const note = standing.assessment?.state === "never" ? "Never assessed: the documents have not been checked against the policies yet, so nothing here is an all-clear. An assessment runs when the reality documents are derived or refreshed (taiga_refresh_reality_documents, paid work: ask first)." : null;
 		if (params.full) return toolResult({
 			summary,
+			...note ? { note } : {},
 			...standing
 		});
 		return toolResult({
 			summary,
+			...note ? { note } : {},
 			productId: standing.productId,
 			hasPolicies: standing.hasPolicies,
 			assessment: standing.assessment,
@@ -4435,7 +4566,7 @@ function registerMaintenanceTools(server, client) {
 	if (!client.hasCapability("products:write")) return;
 	server.registerTool("taiga_ignore_finding", {
 		title: "Ignore or reopen a finding",
-		description: "Ignore a finding that does not apply or whose risk is accepted, with the reason (false_positive, not_reachable, accepted_risk, wont_fix), an optional note and an optional expiry after which it resurfaces if it still exists; or reopen an ignored one (ignored: false). Ignored findings are kept and reviewable. There is no \"mark fixed\": a finding resolves when the next sweep no longer detects it. For a secret that is only in history, rotate the credential outside Taiga, then ignore it with a reason. Ignoring hides a shared signal and can record the team's acceptance of a risk, which is the person's decision: ask the person first.",
+		description: "Ignore a maintenance finding, with a reason, or reopen it. Ignore one that does not apply or whose risk is accepted, with the reason (false_positive, not_reachable, accepted_risk, wont_fix), an optional note and an optional expiry after which it resurfaces if it still exists; or reopen an ignored one (ignored: false). Ignored findings are kept and reviewable. There is no \"mark fixed\": a finding resolves when the next sweep no longer detects it. For a secret that is only in history, rotate the credential outside Taiga, then ignore it with a reason. Ignoring hides a shared signal and can record the team's acceptance of a risk, which is the person's decision: ask the person first.",
 		inputSchema: z.object({
 			findingId,
 			ignored: z.boolean().describe("true ignores the finding, false reopens it"),
@@ -4457,7 +4588,7 @@ function registerMaintenanceTools(server, client) {
 	}));
 	server.registerTool("taiga_fix_finding", {
 		title: "Fix a finding",
-		description: "Ask for a finding's fix: Taiga raises an initiative and adds it to the end of the product's queue, where the line plans it in turn; whether the build then waits for a person is the initiative's review gate, as for any initiative. The fix is a normal run that ends in a pull request you review and merge. With wholeGroup: true it fixes the finding's whole group in one initiative, as the page does: for a dependency, every open advisory on that package at that installed version in one version bump; for code or infrastructure, every location the same rule flagged. Absent for a secret only in history, anything in a submodule, and a dependency with no fixed version (remediableBy says upstream_only); the API refuses those. Starts paid work.",
+		description: "Ask Taiga to fix a maintenance finding: it raises an initiative and adds it to the end of the product's queue, where the line plans it in turn; whether the build then waits for a person is the initiative's review gate, as for any initiative. The fix is a normal run that ends in a pull request you review and merge. With wholeGroup: true it fixes the finding's whole group in one initiative, as the page does: for a dependency, every open advisory on that package at that installed version in one version bump; for code or infrastructure, every location the same rule flagged. Absent for a secret only in history, anything in a submodule, and a dependency with no fixed version (remediableBy says upstream_only); the API refuses those. Starts paid work.",
 		inputSchema: z.object({
 			productId,
 			findingId,
@@ -4483,7 +4614,7 @@ function registerMaintenanceTools(server, client) {
 	}));
 	server.registerTool("taiga_fix_policy_violation", {
 		title: "Fix policy violations",
-		description: "Ask for the fix of a product's policy violations: name a control to cover every violation recorded against it that has no initiative yet, or a single violation (violationId) when the control has more than one. Taiga raises one initiative and adds it to the end of the product's queue, exactly as a finding fix does. The violation stays listed while the work is under way: only the next assessment can record that the documents no longer show it. Starts paid work.",
+		description: "Ask Taiga to fix a product's policy violations (it raises initiatives): name a control to cover every violation recorded against it that has no initiative yet, or a single violation (violationId) when the control has more than one. Taiga raises one initiative and adds it to the end of the product's queue, exactly as a finding fix does. The violation stays listed while the work is under way: only the next assessment can record that the documents no longer show it. Starts paid work.",
 		inputSchema: z.object({
 			productId,
 			controlId: z.string().min(1).max(40).optional().describe("The control's identifier, e.g. SEC-3.4"),
@@ -4533,6 +4664,9 @@ const CONTEXT_BUILD_FIELDS = [
 	"prUrl",
 	"prState",
 	"prMerged",
+	"prDraft",
+	"reviewEscalation",
+	"error",
 	"createdAt"
 ];
 /**
@@ -4595,12 +4729,12 @@ const PARTS = {
 	factory: "factories:read",
 	documents: "products:read",
 	policies: "tenant:documents:read",
-	backlog: "backlog:read",
+	initiatives: "backlog:read",
 	repositories: "products:read",
-	builds: "products:read",
-	attention: "products:read",
+	runs: "products:read",
+	actionRequired: "products:read",
 	maintenance: "products:read",
-	standing: "products:read"
+	policyStanding: "products:read"
 };
 /** What the API said when a part failed, in the words the bundle reports. */
 function unavailableReason(reason) {
@@ -4765,8 +4899,8 @@ async function backlogPart(client, productId) {
 * The linked repositories. The route serves one page of 100 and takes no
 * cursor, so past that the bundle says the list is cut rather than complete.
 */
-async function repositoriesPart(client, productId) {
-	const result = await client.listProductRepositories(productId);
+async function repositoriesPart(links) {
+	const result = await links();
 	return {
 		items: pickFields(result.data, REPOSITORY_SUMMARY_FIELDS),
 		truncated: result.nextCursor !== null
@@ -4774,7 +4908,7 @@ async function repositoriesPart(client, productId) {
 }
 async function buildsPart(client, productId) {
 	const rows = (await client.listBuildRuns(productId, { limit: BUILDS_IN_CONTEXT })).data;
-	return pickFields(rows, CONTEXT_BUILD_FIELDS).map(readableRun);
+	return pickFields(rows, CONTEXT_BUILD_FIELDS).map(readableRow);
 }
 /**
 * What waits on a person for this product, counted by kind (PRO-2800): the
@@ -4815,30 +4949,35 @@ async function maintenancePart(client, productId) {
 }
 /** Where the product stands against the policies, as counts; taiga_get_policy_standing has each violation. */
 async function standingPart(client, productId) {
-	const summary = standingSummary((await client.getPolicyStanding(productId)).data);
+	const standing = (await client.getPolicyStanding(productId)).data;
+	const summary = standingSummary(standing);
+	const state = standing.assessment?.state;
 	return {
 		openViolations: summary.violations,
 		bySeverity: summary.bySeverity,
-		controlsViolated: summary.controls
+		controlsViolated: summary.controls,
+		...state === "never" || state === "failed" ? { note: `The assessment ${state === "never" ? "has never run" : "failed"}: no violations here is not an all-clear.` } : {}
 	};
 }
 async function productContext(client, product, options) {
 	const productId = product.id;
 	const granted = (part) => client.hasCapability(PARTS[part]);
 	const notGranted = Object.keys(PARTS).filter((part) => !granted(part));
+	let linksRead;
+	const links = () => linksRead ??= client.listProductRepositories(productId);
 	const fetchers = {
 		factory: () => factoryPart(client, String(product.factoryId)),
 		documents: () => documentsPart(client, product, options.documents),
 		policies: () => policiesPart(client),
-		backlog: () => backlogPart(client, productId),
-		repositories: () => repositoriesPart(client, productId),
-		builds: () => buildsPart(client, productId),
-		attention: () => attentionPart(client, productId),
+		initiatives: () => backlogPart(client, productId),
+		repositories: () => repositoriesPart(links),
+		runs: () => buildsPart(client, productId),
+		actionRequired: () => attentionPart(client, productId),
 		maintenance: () => maintenancePart(client, productId),
-		standing: () => standingPart(client, productId)
+		policyStanding: () => standingPart(client, productId)
 	};
 	const parts = Object.keys(fetchers).filter(granted);
-	const [settled, readiness] = await Promise.all([Promise.allSettled(parts.map((part) => fetchers[part]())), setupReadiness(client, product)]);
+	const [settled, readiness] = await Promise.all([Promise.allSettled(parts.map((part) => fetchers[part]())), setupReadiness(client, product, links)]);
 	const bundle = { product: {
 		...pickFields([product], PRODUCT_SUMMARY_FIELDS)[0],
 		projectType: isImportedProduct(product) ? "brownfield" : "greenfield",
@@ -4875,7 +5014,7 @@ function registerContextTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_get_product_context", {
 		title: "Get product context",
-		description: `Where a product stands and everything a coding session starts from, in one call. Name the product by ID, slug or the git remote URL of a checkout. It carries: the product (and, while in setup, readiness: what it still needs and the next move); its factory with the instructions in full; the specification and architecture as outlines (section ids and sizes); every published policy as its section ids; the open initiatives (not the done or canceled ones: taiga_list_initiatives has those); the linked repositories; the latest runs, each with its outcome in a sentence; attention, what waits on a person for it, counted by kind; maintenance, open findings by severity and the last sweep; standing, open policy violations by severity. A part the API refused or failed is named under unavailable; a part the key cannot read under notGranted; neither is shown as empty. Before writing code, documents: budget brings the whole sections that fit, about ${DOCUMENT_BUDGET / 1e3}k characters each, and full brings them whole (tens of thousands of tokens on a large product). Unlike taiga_get_product, which is the product record and its settings alone. Call this first, then read what you need.`,
+		description: `Where a product stands, in one call: the first read for any question about a product. Name it by ID, slug or the git remote URL of a checkout. The parts: product (and, while in setup, readiness: what it still needs and the next move); factory, with its instructions in full; documents, the specification and architecture as outlines (section ids and sizes); policies, each published policy with its section ids; initiatives, the open ones (taiga_list_initiatives has the done and canceled); repositories; runs, the latest ten, each with its outcome in a sentence; actionRequired, what waits on a person, counted by kind; maintenance, open findings by severity and the last sweep; policyStanding, open policy violations by severity. A part the API refused or failed is named under unavailable, a part the key cannot read under notGranted; neither is shown as empty. Before writing code, documents: budget brings the whole sections that fit, about ${DOCUMENT_BUDGET / 1e3}k characters each, and full brings them whole. taiga_get_product is the product record and its settings alone.`,
 		inputSchema: z.object({
 			productId: productId.optional(),
 			slug: slug.optional(),
@@ -4930,7 +5069,7 @@ function registerAutonomyTools(server, client) {
 	}));
 	if (client.hasCapability("backlog:write")) server.registerTool("taiga_set_auto_merge", {
 		title: "Set whether an initiative's pull request merges on its own",
-		description: "An initiative's own switch for merging on its own: true lets its pull request merge itself once the repository's own rules pass (required checks, reviews, a code reviewer you made Taiga wait for); false makes it wait for a person; null follows the product's default. The final word within what the organization and factories allow: where either has turned autonomous merge off, true changes nothing. Taiga merges through your rules, never around them.",
+		description: "Set whether one initiative's pull request merges on its own: true lets its pull request merge itself once the repository's own rules pass (required checks, reviews, a code reviewer you made Taiga wait for); false makes it wait for a person; null follows the product's default. The final word within what the organization and factories allow: where either has turned autonomous merge off, true changes nothing. Taiga merges through your rules, never around them.",
 		inputSchema: z.object({
 			initiativeId: idInput("initiative", "taiga_list_initiatives (query finds one by title) gives it"),
 			autoMerge: z.boolean().nullable().describe("true merges on its own, false waits for a person, null follows the product")
@@ -4991,22 +5130,62 @@ function itemRow(row, now, full) {
 	};
 }
 /** What is open, counted by product and kind: the answer to "what needs attention" without reading every row. */
-function summaryOf(rows) {
+function summaryOf(rows, stale) {
 	const byProduct = /* @__PURE__ */ new Map();
 	for (const row of rows) {
 		const key = String(row["productId"]);
-		const entry = byProduct.get(key) ?? {
+		const entry = byProduct.get(key) ?? (row["productName"] ? {
 			productId: key,
-			product: row["productName"] ?? key,
+			product: row["productName"],
 			open: 0,
 			byKind: {}
-		};
+		} : {
+			productId: key,
+			open: 0,
+			byKind: {}
+		});
 		entry.open += 1;
 		entry.byKind[String(row["kind"])] = (entry.byKind[String(row["kind"])] ?? 0) + 1;
+		if (stale.has(String(row["id"]))) entry.stale = (entry.stale ?? 0) + 1;
 		byProduct.set(key, entry);
 	}
 	return [...byProduct.values()].sort((a, b) => b.open - a.open);
 }
+/** Pull request reviews checked against their run and initiative; past this a row is left as it is. */
+const STALE_CHECKS = 10;
+/**
+* Which "Review & merge" items no longer stand, and why (PRO-2800): the run's
+* pull request closed or merged, or its initiative was canceled or finished
+* without it. Two reviewing agents counted such leftovers as live gates; the
+* row still is open in Action Required, so this says what it is now rather
+* than hiding it. Best effort, a handful of runs: a failed read leaves the
+* row as it was.
+*/
+async function staleReviews(client, rows) {
+	const byId = new Map(rows.filter((row) => row["kind"] === "review_pr" && row["subjectType"] === "build_run").map((row) => [String(row["id"]), row]));
+	const candidates = [...byId.values()].slice(0, STALE_CHECKS);
+	let unchecked = byId.size - candidates.length;
+	const out = /* @__PURE__ */ new Map();
+	await Promise.all(candidates.map(async (row) => {
+		try {
+			const run = (await client.getBuildRun(String(row["subjectId"]))).data;
+			if (run["prMerged"] === true) return void out.set(String(row["id"]), "its pull request has merged");
+			if (run["prState"] === "closed") return void out.set(String(row["id"]), "its pull request was closed");
+			if (typeof run["backlogItemId"] !== "string") return;
+			if (!client.hasCapability("backlog:read")) return void (unchecked += 1);
+			const item = (await client.getBacklogItem(run["backlogItemId"])).data;
+			if (item["state"] === "canceled" || item["status"] === "canceled") out.set(String(row["id"]), "its initiative was canceled; the pull request is still open on the forge");
+			else if (item["state"] === "done" || item["status"] === "done") out.set(String(row["id"]), "its initiative is done; this run is not the one that landed it");
+		} catch (error) {
+			if (!(error instanceof TaigaApiError || isNetworkFailure(error))) throw error;
+			unchecked += 1;
+		}
+	}));
+	return {
+		stale: out,
+		unchecked
+	};
+}
 /** Pages read for the summary; past this it says it counted only those. */
 const SUMMARY_PAGE = 100;
 const SETUP_TASK_FIELDS = [
@@ -5067,11 +5246,18 @@ function sameKeyOnce(rows) {
 	}
 	return out;
 }
+/** A page of folded rows, saying how many records it folded so totalCount (records) and the rows reconcile. */
+function folded(rows, nextCursor, records) {
+	return {
+		...page(rows, nextCursor),
+		...rows.length < records ? { recordsOnPage: records } : {}
+	};
+}
 function registerInboxTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_list_action_required", {
 		title: "List what needs a person",
-		description: "Read Action Required, where work comes back to a person, shared by the team: things to review (a plan, a set of initiatives, a document decision, a pull request, maintenance findings, new policy violations) and things to set up that only a person can (a secret, an environment variable, an account, a package registry, a cloud permission). Across every product the key can open, or one product. The first page opens with summary: what is open, counted by product and kind, so \"what needs attention\" is one call, and totalCount. Each row says how many days it has waited (waitingDays) and, for a pull request review, the prUrl; an old item is still open, not stale. category gate is the reviews, setup the setup items; resolved: true reads the archive. An item snoozed until later is left out until then (snoozedHidden counts them). full: true adds each item's metadata. Unlike taiga_list_setup_tasks, which lists the setup items with exactly what to set and where.",
+		description: "What waits on a person: reviews and setup items, with a summary by product. The inbox is the team's, not one person's. It holds things to review (a plan, a set of initiatives, a document decision, a pull request, maintenance findings, new policy violations) and things to set up that only a person can (a secret, an environment variable, an account, a package registry, a cloud permission). Across every product the key can open, or one product. The first page opens with summary: what is open, counted by product and kind, so \"what needs attention\" is one call, and totalCount. Each row says how many days it has waited (waitingDays) and, for a pull request review, the prUrl. A pull request review that no longer stands (its pull request merged or closed, or its initiative canceled or done) says so under stale, and the summary counts those per product. category gate is the reviews, setup the setup items; resolved: true reads the archive. An item snoozed until later is left out until then (snoozedHidden counts them). full: true adds each item's metadata. Unlike taiga_list_setup_tasks, which lists the setup items with exactly what to set and where.",
 		inputSchema: z.object({
 			productId: productId.optional(),
 			category: z.enum(["gate", "setup"]).optional().describe("gate: things to review; setup: things to set up"),
@@ -5104,19 +5290,33 @@ function registerInboxTools(server, client) {
 		const rows = result.data;
 		const due = rows.filter(isDue);
 		const hidden = rows.length - due.length;
+		const overviewDue = overview ? overview.data.filter(isDue) : [];
+		const checked = resolved ? {
+			stale: /* @__PURE__ */ new Map(),
+			unchecked: 0
+		} : await staleReviews(client, [...due, ...overviewDue]);
+		const stale = checked.stale;
 		return toolResult({
 			...overview ? {
-				summary: summaryOf(overview.data.filter(isDue)),
+				summary: summaryOf(overviewDue, stale),
 				...overview.nextCursor ? { summaryNote: `The summary counts the first ${SUMMARY_PAGE} items.` } : {}
 			} : {},
-			...page(due.map((row) => itemRow(row, now, full === true)), result.nextCursor),
+			...page(due.map((row) => {
+				const item = itemRow(row, now, full === true);
+				const why = stale.get(String(row["id"]));
+				return why ? {
+					...item,
+					stale: why
+				} : item;
+			}), result.nextCursor),
 			...totalOf(result),
-			...hidden > 0 ? { snoozedHidden: hidden } : {}
+			...hidden > 0 ? { snoozedHidden: hidden } : {},
+			...checked.unchecked > 0 ? { staleNote: `${checked.unchecked} pull request review${checked.unchecked === 1 ? " was" : "s were"} not checked for staleness (past the cap, or the read was refused).` } : {}
 		});
 	}));
 	server.registerTool("taiga_list_setup_tasks", {
 		title: "List setup tasks",
-		description: "The setup tasks agents raised for work only a person can do, with what exactly to set and where: the name of an environment variable, secret or API key to create (key; never its value, which Taiga does not store or display), the provider page to do it on, and the phase that says when it blocks you (prereq: before the deploy, which fails without it; wiring: connecting generated values back to providers; followup: billing approvals, extra permissions and the like that can wait until after launch). A build does not wait for any of them. Across every product the key can open (each row names its product), or one. The tasks still to do, oldest first, the order they depend on each other; includeDone: true adds the done and dismissed ones. The first page says how many there are on every page (totalCount). One row per variable: a variable filed twice (as a secret and as an environment variable) lists the other records under alsoFiledAs, an open one first; within a page, and totalCount counts every record. Unlike taiga_list_action_required, whose setup items are the same work as rows to resolve, this says exactly what to set and where.",
+		description: "What a person must set up for a product (secrets, variables, accounts), with exactly what and where. These are the tasks agents raised for work only a person can do: the name of an environment variable, secret or API key to create (key; never its value, which Taiga does not store or display), the provider page to do it on, and the phase that says when it blocks you (prereq: before the deploy, which fails without it; wiring: connecting generated values back to providers; followup: billing approvals, extra permissions and the like that can wait until after launch). A build does not wait for any of them. Across every product the key can open (each row names its product), or one. The tasks still to do, oldest first, the order they depend on each other; includeDone: true adds the done and dismissed ones. The first page says how many there are on every page (totalCount). One row per variable: a variable filed twice (as a secret and as an environment variable) lists the other records under alsoFiledAs, an open one first (folded within a page). totalCount counts records, and a page that folded some says recordsOnPage. Unlike taiga_list_action_required, whose setup items are the same work as rows to resolve, this says exactly what to set and where.",
 		inputSchema: z.object({
 			productId: productId.optional(),
 			includeDone: z.boolean().optional().describe("Also the tasks already done or dismissed (default false)"),
@@ -5131,7 +5331,7 @@ function registerInboxTools(server, client) {
 			...params.cursor === void 0 ? { withTotal: true } : {}
 		});
 		return toolResult({
-			...page(sameKeyOnce(pickFields(result.data, SETUP_TASK_FIELDS)), result.nextCursor),
+			...folded(sameKeyOnce(pickFields(result.data, SETUP_TASK_FIELDS)), result.nextCursor, result.data.length),
 			...totalOf(result)
 		});
 	}));
@@ -5297,7 +5497,7 @@ function registerKnowledgeTools(server, client) {
 	if (!client.hasCapability("customDocuments:write")) return;
 	server.registerTool("taiga_add_knowledge", {
 		title: "Add knowledge",
-		description: "File a Markdown or plain-text reference document as knowledge, at the level it is relevant: a product (productId), a factory (factoryId), or the organization (neither; that takes an owner or admin, because every factory and product inherits it). Good candidates are what a new engineer would be handed to read: specifications and contracts to conform to, glossaries and code lists, third-party documentation, internal write-ups. A rule that applies every time belongs in instructions instead. The file is processed before agents can read it; taiga_list_knowledge says when it is ready. PDFs and spreadsheets are added in the web. The same content already filed at that level comes back as that file, with deduplicated: true: it was not created here, so do not delete it as if it were. Every agent at that level reads it from then on, and processing it is paid work.",
+		description: "File a reference document as knowledge for agents to search: Markdown or plain text, at the level it is relevant: a product (productId), a factory (factoryId), or the organization (neither; that takes an owner or admin, because every factory and product inherits it). Good candidates are what a new engineer would be handed to read: specifications and contracts to conform to, glossaries and code lists, third-party documentation, internal write-ups. A rule that applies every time belongs in instructions instead. The file is processed before agents can read it; taiga_list_knowledge says when it is ready. PDFs and spreadsheets are added in the web. The same content already filed at that level comes back as that file, with deduplicated: true: it was not created here, so do not delete it as if it were. Every agent at that level reads it from then on, and processing it is paid work.",
 		inputSchema: z.object({
 			...scopeInputs,
 			fileName: z.string().trim().min(1).max(200).regex(/\.(md|txt)$/i, "A Markdown (.md) or plain-text (.txt) file name").describe("The file name, ending in .md or .txt"),
@@ -5436,7 +5636,7 @@ function registerObserveTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_get_deployments", {
 		title: "Get what runs where",
-		description: "What is running in each of a product's environments now, anything deploying to them, and the recent history, newest first: each deployment with its commit, pull request, status, who deployed it and, for a failure, the error the provider reported. What runs is the most recent deployment that actually succeeded, so a newer failed attempt shows beside the version still running, not in its place. The history is mirrored from the provider, including deployments made outside Taiga; syncStatus says when it last synced. Pass environmentId for one environment's history. Taiga observes deployments and never performs them.",
+		description: "What runs in each of a product's environments, and recent deployments: what is running now, anything deploying, and the recent history, newest first: each deployment with its commit, pull request, status, who deployed it and, for a failure, the error the provider reported. What runs is the most recent deployment that actually succeeded, so a newer failed attempt shows beside the version still running, not in its place. The history is mirrored from the provider, including deployments made outside Taiga; syncStatus says when it last synced. Pass environmentId for one environment's history. Taiga observes deployments and never performs them.",
 		inputSchema: z.object({
 			productId,
 			environmentId: environmentId.optional(),
@@ -5484,7 +5684,7 @@ function registerObserveTools(server, client) {
 	}));
 	server.registerTool("taiga_get_delivery_metrics", {
 		title: "Get delivery metrics",
-		description: "DORA's five software delivery metrics for one environment (the one marked production, as the page reports them), computed from its deployment history over the last 30, 60 or 90 days: deployment frequency, lead time and failed deployment recovery time (throughput), change-failure rate and rework rate (instability), each with its trend against the window before, and a performance band for all but rework rate, which DORA has published none for. Failures and recoveries are read from deployments, not incidents. A trend built on fewer than ten deployments is approximate; a metric no deployment fed says so instead of showing a number. Previews and checks do not count.",
+		description: "DORA's five delivery metrics for one environment (the one marked production, as the page reports them), computed from its deployment history over the last 30, 60 or 90 days: deployment frequency, lead time and failed deployment recovery time (throughput), change-failure rate and rework rate (instability), each with its trend against the window before, and a performance band for all but rework rate, which DORA has published none for. Failures and recoveries are read from deployments, not incidents. A trend built on fewer than ten deployments is approximate; a metric no deployment fed says so instead of showing a number. Previews and checks do not count.",
 		inputSchema: z.object({
 			productId,
 			environmentId,
@@ -5497,7 +5697,7 @@ function registerObserveTools(server, client) {
 	}));
 	server.registerTool("taiga_get_monitoring", {
 		title: "Get a product's monitoring",
-		description: "How a product's environments are doing: each environment's current health from Taiga's availability checks of its App URL, with its uptime and when it was last checked; a status Taiga cannot verify now reads as not checked rather than the last thing it knew, and a new environment as baseline learning. With environmentId, that environment's uptime over a 30, 60 or 90-day window, and the experience signals the beacon reports (Core Web Vitals, JavaScript errors, client-observed API health) where it is installed; until then they read as not set up, which means no data, not good data. Setting up the beacon raises an initiative from the environment's settings in the web.",
+		description: "How a product's environments are doing (health, uptime): each environment's current health from Taiga's availability checks of its App URL, with its uptime and when it was last checked; a status Taiga cannot verify now reads as not checked rather than the last thing it knew, and a new environment as baseline learning. With environmentId, that environment's uptime over a 30, 60 or 90-day window, and the experience signals the beacon reports (Core Web Vitals, JavaScript errors, client-observed API health) where it is installed; until then they read as not set up, which means no data, not good data. Setting up the beacon raises an initiative from the environment's settings in the web.",
 		inputSchema: z.object({
 			productId,
 			environmentId: environmentId.optional(),
@@ -5606,7 +5806,7 @@ function registerProductDocumentWrites(server, client) {
 	}, (params) => runTool(() => publishDraft(productScope(params.productId, params.type))));
 	server.registerTool("taiga_mark_product_document_reviewed", {
 		title: "Mark a product document reviewed",
-		description: "Record that a person reviewed a product document's latest published version, as the Documents page shows it beside each version; once every published document is reviewed, the product's review item in Action Required resolves. The mark says a human read it, so make it only when the person tells you they have: reading it yourself is not a review.",
+		description: "Record that a person reviewed a product document: its latest published version, as the Documents page shows it beside each version; once every published document is reviewed, the product's review item in Action Required resolves. The mark says a human read it, so make it only when the person tells you they have: reading it yourself is not a review.",
 		inputSchema: z.object({
 			productId,
 			type: reviewableType
@@ -20477,7 +20677,7 @@ function registerRepositoryTools(server, client) {
 	if (!client.hasCapability("vcs:manage")) return;
 	server.registerTool("taiga_link_repository", {
 		title: "Link a repository to a product",
-		description: "Link a repository the GitHub connection can reach (taiga_list_linkable_repositories gives its id) to a product, or with replacesRepositoryId swap the one linked now for it in one step (naming the same repository there changes nothing; linking one already linked without it is refused). A link Taiga manages (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 in the background.",
+		description: "Link a GitHub repository to a product: one the GitHub connection can reach (taiga_list_linkable_repositories gives its id), or with replacesRepositoryId swap the one linked now for it in one step (naming the same repository there changes nothing; linking one already linked without it is refused). A link Taiga manages (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 in the background.",
 		inputSchema: z.object({
 			productId,
 			githubRepositoryId: idInput("GitHub repository", "taiga_list_linkable_repositories gives it"),
@@ -20793,7 +20993,7 @@ function registerSetupTools(server, client) {
 	}));
 	server.registerTool("taiga_update_product", {
 		title: "Change a product's settings",
-		description: "Change a product's name (its slug follows the name, so links to the product change) or what Taiga builds for it: its infrastructure code and CI/CD pipelines (null returns one to the organization default), the sentence on how a half Taiga does not build is done today, and whether it inherits the organization's design standards (null follows the default for how the product started). Later plans read the new answer; work already planned is not redone. Autonomy is taiga_set_product_autonomy.",
+		description: "Change a product's name or what Taiga builds for it. A new name changes the slug, so links to the product change. What Taiga builds for it: its infrastructure code and CI/CD pipelines (null returns one to the organization default), the sentence on how a half Taiga does not build is done today, and whether it inherits the organization's design standards (null follows the default for how the product started). Later plans read the new answer; work already planned is not redone. Autonomy is taiga_set_product_autonomy.",
 		inputSchema: z.object({
 			productId,
 			name: z.string().trim().min(1).max(255).optional().describe("A new name"),
@@ -20816,7 +21016,7 @@ function registerSetupTools(server, client) {
 	}));
 	server.registerTool("taiga_refresh_reality_documents", {
 		title: "Refresh a product's documents from its code",
-		description: "Derive the reality documents again from the code on the branch Taiga works on (the link's effectiveBranch: the chosen branch, or the repository's default): all of them, or the ones named (with what they are derived from). For a document the import misread, refresh it rather than importing again; unchanged sections are not republished. Runs an agent in the background and returns the job; taiga_wait_for_job says when it is done.",
+		description: "Derive the reality documents again from the code, on the branch Taiga works on (the link's effectiveBranch: the chosen branch, or the repository's default): all of them, or the ones named (with what they are derived from). For a document the import misread, refresh it rather than importing again; unchanged sections are not republished. Runs an agent in the background and returns the job; taiga_wait_for_job says when it is done.",
 		inputSchema: z.object({
 			productId,
 			docTypes: z.array(z.enum(REALITY_DERIVED_DOCUMENT_TYPES)).min(1).max(REALITY_DERIVED_DOCUMENT_TYPES.length).optional().describe("The documents to refresh; omit for all")
@@ -21099,6 +21299,8 @@ const RUN_REPORT_FIELDS = [
 	"prState",
 	"prDraft",
 	"prMerged",
+	"reviewEscalation",
+	"error",
 	"prNumber",
 	"baseBranch",
 	"actions"
@@ -21123,7 +21325,7 @@ function judgeBuild(until) {
 function registerWaitTools(server, client, options) {
 	if (client.hasCapability("backlog:read")) server.registerTool("taiga_wait_for_initiative", {
 		title: "Wait for an initiative",
-		description: "Wait until an initiative reaches a point, instead of reading it again and again: changed (anything about where it is or its latest run), planned (its plan landed), your_turn (it waits on a person: a plan to review, a pull request, a flag), pr_open (a pull request open now; a merged or closed one does not count), run_settled (its latest run stopped moving) or done (finished; a canceled one stops the wait). Returns as soon as that holds (reached: true), early when it cannot hold without a person (a flag, a failed plan, a plan waiting for its verdict, a pull request waiting for a review, a cancelled initiative, or a landed plan whose review gate cannot be read; stoppedBecause says which), or at the timeout with reached: false: call again to keep waiting. Conditions are states, not events: an initiative whose latest run is already settled answers run_settled at once; item is null when not even the first read answered in time. Planning takes minutes and a build up to an hour.",
+		description: "Wait for an initiative to reach a point (planned, building, a pull request, done), instead of reading it again and again: changed (anything about where it is or its latest run), planned (its plan landed), your_turn (it waits on a person: a plan to review, a pull request, a flag), pr_open (a pull request open now; a merged or closed one does not count), run_settled (its latest run stopped moving) or done (finished; a canceled one stops the wait). Returns as soon as that holds (reached: true), early when it cannot hold without a person (a flag, a failed plan, a plan waiting for its verdict, a pull request waiting for a review, a cancelled initiative, or a landed plan whose review gate cannot be read; stoppedBecause says which), or at the timeout with reached: false: call again to keep waiting. Conditions are states, not events: an initiative whose latest run is already settled answers run_settled at once; item is null when not even the first read answered in time. Planning takes minutes and a build up to an hour.",
 		inputSchema: z.object({
 			initiativeId: idInput("initiative", "taiga_list_initiatives (query finds one by title) gives it"),
 			until: z.enum(ITEM_CONDITIONS).describe("What to wait for"),
@@ -21156,7 +21358,7 @@ function registerWaitTools(server, client, options) {
 	}));
 	if (client.hasCapability("products:read")) server.registerTool("taiga_wait_for_run", {
 		title: "Wait for a run",
-		description: "Wait until a coding agent's run reaches a point: changed (status, steps or pull request), step_done (one more step finished), pr_open (open now, not merged or closed) or settled (it stopped moving: in review, completed, failed, stopped). Returns as soon as that holds (reached: true), early when the run settled without it (stoppedBecause; changed waits on, since a person resuming the run is a change), or at the timeout with reached: false: call again to keep waiting. Conditions are states: a run already settled answers settled at once; run is null when not even the first read answered in time.",
+		description: "Wait for a run to reach a point (a step, a pull request, settled): changed (status, steps or pull request), step_done (one more step finished), pr_open (open now, not merged or closed) or settled (it stopped moving: in review, completed, failed, stopped). Returns as soon as that holds (reached: true), early when the run settled without it (stoppedBecause; changed waits on, since a person resuming the run is a change), or at the timeout with reached: false: call again to keep waiting. Conditions are states: a run already settled answers settled at once; run is null when not even the first read answered in time.",
 		inputSchema: z.object({
 			runId: idInput("run", "taiga_list_runs gives it"),
 			until: z.enum(BUILD_CONDITIONS).describe("What to wait for"),
@@ -21172,7 +21374,7 @@ function registerWaitTools(server, client, options) {
 		return toolResult({
 			until: params.until,
 			...outcome,
-			run: now ? readableRun(pickFields([now], RUN_REPORT_FIELDS)[0]) : null
+			run: now ? readableRow(pickFields([now], RUN_REPORT_FIELDS)[0]) : null
 		});
 	}));
 	if (client.hasCapability("products:read")) server.registerTool("taiga_wait_for_job", {
@@ -21206,9 +21408,10 @@ function registerWaitTools(server, client, options) {
 * model learns the tool's real shape. Applied here, once, so no tool can be
 * registered without it.
 */
-function withStrictInputs(server) {
+function withStrictInputs(server, registered) {
 	const register = server.registerTool.bind(server);
 	server.registerTool = ((name, config, callback) => {
+		registered.set(name, config.annotations);
 		const schema = config.inputSchema;
 		if (schema !== void 0 && !(schema instanceof z.ZodObject)) throw new Error(`Tool ${name}: inputSchema must be a z.object() so unknown arguments can be refused`);
 		const handler = callback;
@@ -21247,7 +21450,7 @@ const ALWAYS_LOAD = /* @__PURE__ */ new Set([
 function writeNotice(name, annotations) {
 	if (!annotations || annotations.readOnlyHint === void 0) throw new Error(`Tool ${name}: annotations must say whether it is read-only`);
 	if (annotations.readOnlyHint) return "";
-	return annotations.destructiveHint ? "Acts on paid or shared work: ask the person first. " : "Writes. ";
+	return annotations.destructiveHint ? "Ask first: paid or shared work. " : "Writes. ";
 }
 /**
 * Register all MCP tools, resources and prompts based on the API key's effective capabilities.
@@ -21255,7 +21458,8 @@ function writeNotice(name, annotations) {
 * never sees tools it can't use.
 */
 function registerAllTools(server, client, options = {}) {
-	withStrictInputs(server);
+	const registered = /* @__PURE__ */ new Map();
+	withStrictInputs(server, registered);
 	registerProductTools(server, client);
 	registerDocumentTools(server, client);
 	registerBacklogTools(server, client);
@@ -21272,9 +21476,39 @@ function registerAllTools(server, client, options = {}) {
 	registerRepositoryTools(server, client);
 	registerWaitTools(server, client, options.wait ?? DEFAULT_WAIT_OPTIONS);
 	registerContextTools(server, client);
+	if (registered.size > 0) registerWhoami(server, client, registered);
 	registerResources(server, client);
 	registerPrompts(server, client);
 }
+/**
+* Who this key is and what it may do (PRO-2800): reviewing agents read tool
+* descriptions saying "owners and admins link repositories" with no way to
+* learn their own role until a write was refused. Registered last, so it can
+* name every tool the key was given.
+*/
+function registerWhoami(server, client, registered) {
+	server.registerTool("taiga_whoami", {
+		title: "Who am I",
+		description: "Who this API key acts as and what it may do: the person's email and organization role, the key's scopes (null means every capability the person has), its capabilities, and the tools it was given, split into reads, writes, and the ask-first writes (paid agent work or changes others see). A tool the key's capabilities do not cover is not offered at all, rather than refused when called.",
+		inputSchema: z.object({}),
+		annotations: READ_ONLY
+	}, () => runTool(async () => {
+		const me = client.getIntrospection();
+		const tools = [...registered.entries()].filter(([name]) => name !== "taiga_whoami");
+		const named = (pick) => tools.filter(([, notes]) => pick(notes)).map(([name]) => name);
+		return toolResult({
+			email: me?.email ?? null,
+			role: me?.role ?? null,
+			scopes: me?.scopes ?? null,
+			capabilities: me?.capabilities ?? [],
+			tools: {
+				reads: named((notes) => notes?.readOnlyHint === true),
+				writes: named((notes) => notes?.readOnlyHint === false && notes.destructiveHint !== true),
+				askFirst: named((notes) => notes?.readOnlyHint === false && notes.destructiveHint === true)
+			}
+		});
+	}));
+}
 //#endregion
 //#region src/tools/instructions.ts
 /**
@@ -21292,20 +21526,25 @@ const SERVER_INSTRUCTIONS = [
 	"Taiga is a policy-aware software delivery platform: an organization's policies and knowledge, its factories",
 	"and products, each product's initiatives (its backlog), the line that plans and builds them one at a time, the",
 	"coding agent's runs and pull requests, maintenance findings, and Action Required, where work waits on a person.",
-	"Search these tools whenever the person asks about a Taiga product, an initiative, a run or pull request, policy",
-	"or compliance, findings, deployments or monitoring, or setting a product up.",
+	"Use these tools (names start with taiga_) whenever the person asks about a Taiga product, an initiative, a run",
+	"or pull request, policy or compliance, findings, deployments, or setting a product up.",
 	"",
-	"**Start here.** taiga_get_product_context (the product by git remote URL, slug or ID) gives its state in one",
-	"call: what it still needs while in setup, its documents as outlines, policies as section ids, open initiatives,",
-	"recent runs with their outcome, and what waits on a person. Then read only what you need. Across products,",
-	"taiga_list_products and taiga_list_action_required.",
+	"**Start here.** taiga_get_product_context (a product by git remote URL, slug or ID) says where it stands in one",
+	"call: what it still needs while in setup, documents as outlines, policies as section ids, open initiatives,",
+	"recent runs with their outcome, what waits on a person, findings and policy violations. Then read only what you",
+	"need. Across products: taiga_list_products, taiga_list_action_required. taiga_whoami says what this key may do.",
 	"",
 	"**Words.** An initiative is a unit of work in the backlog; a run is one attempt by the coding agent to build it;",
 	"the line is the product's queue; a factory owns a set of products. IDs are UUIDs, never names; a NOT_FOUND names",
-	"the tool that lists the right ones. A refusal carries the reason: say it as it is.",
+	"the tool that lists the right ones. A GitHub repository id is not a repository link id. Say a refusal as it is.",
+	"",
+	"**Reading.** Lists page with nextCursor (Action Required, setup tasks, findings: totalCount). A document has two",
+	"timelines: plan (what was meant) and reality (derived from the code). outcome, situation and nextStep are",
+	"one-sentence summaries of the record they sit on; read the record for the detail.",
 	"",
-	"**Before you write.** A tool that writes says so first: \"Writes.\" or \"Acts on paid or shared work: ask the",
-	"person first.\" Ask before the second kind: it starts paid agent work, interrupts it, or changes what others see.",
+	"**Before you write.** A tool that writes opens with \"Writes.\" or \"Ask first:\". Before an \"Ask first\" tool, tell",
+	"the person what you are about to do and wait for their yes: it starts paid agent work, interrupts it, or changes",
+	"what others see.",
 	"",
 	"**Only in the web:** connecting GitHub, members and roles, the Discovery conversation of a product started from",
 	"scratch, stamping checks, starting a run over, and deleting anything."