@opsee/mcp-server 0.11.6 → 0.11.9

package/src/client/api.ts

@@ -4,6 +4,7 @@ import { create } from "@bufbuild/protobuf";
 import type { GenService } from "@bufbuild/protobuf/codegenv1";
 import { authManager } from "../auth/manager.js";
 import { getCurrentToken } from "../auth/token-context.js";
+import { clientInterceptor, MCP_CLIENT_MARKER } from "./marker.js";
 import {
   PaginationSchema,
   type Pagination,
@@ -40,9 +41,6 @@ const authInterceptor: Interceptor = (next) => async (req) => {
   if (token) {
     req.header.set("Authorization", `Bearer ${token}`);
   }
-  // Marks an automation client so board events carry the system actor: an agent using a user's token
-  // must not be self-skipped on that user's board (ADR-0002 §5).
-  req.header.set("X-Opsee-Client", "mcp");
   return await next(req);
 };
 
@@ -77,23 +75,21 @@ export function defaultPagination(
   });
 }
 
-let transport: ReturnType<typeof createConnectTransport> | null = null;
 let cachedClients: ApiClients | null = null;
 
-function getTransport() {
-  if (!transport) {
-    transport = createConnectTransport({
-      baseUrl: authManager.getServerUrl(),
-      httpVersion: "1.1",
-      interceptors: [authInterceptor, paginationInterceptor],
-    });
-  }
-  return transport;
+export interface ClientOptions {
+  /** Value sent as X-Opsee-Client; the MCP server's own clients send `mcp` (the default). */
+  marker?: string;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function makeClient<T extends GenService<any>>(service: T): Client<T> {
-  return createClient(service, getTransport());
+function makeTransport({ marker = MCP_CLIENT_MARKER }: ClientOptions) {
+  return createConnectTransport({
+    baseUrl: authManager.getServerUrl(),
+    httpVersion: "1.1",
+    // The marker tells the backend this is an automation client acting with a user's token, so board
+    // events carry the system actor and are not self-skipped on that user's board (ADR-0002 §5).
+    interceptors: [authInterceptor, clientInterceptor(marker), paginationInterceptor],
+  });
 }
 
 export type ApiClients = {
@@ -123,34 +119,45 @@ export type ApiClients = {
   milestoneDocPages: Client<typeof MilestoneDocPageService>;
 };
 
+/** Builds a fresh client set over its own transport. Another client (the `opsee` CLI) passes its
+ * own marker; the MCP server itself uses the cached `getClients()`. */
+export function createClients(options: ClientOptions = {}): ApiClients {
+  const transport = makeTransport(options);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const makeClient = <T extends GenService<any>>(service: T): Client<T> =>
+    createClient(service, transport);
+  return {
+    projects: makeClient(ProjectService),
+    tasks: makeClient(TaskService),
+    boards: makeClient(BoardService),
+    boardColumns: makeClient(BoardColumnService),
+    cycles: makeClient(CycleService),
+    docSpaces: makeClient(DocSpaceService),
+    docPages: makeClient(DocPageService),
+    docPageVersions: makeClient(DocPageVersionService),
+    taskTypes: makeClient(TaskTypeService),
+    taskPriorities: makeClient(TaskPriorityService),
+    users: makeClient(UserService),
+    vcsIntegrations: makeClient(VCSIntegrationService),
+    milestones: makeClient(MilestoneService),
+    milestoneTasks: makeClient(MilestoneTaskService),
+    labels: makeClient(LabelService),
+    taskLabels: makeClient(TaskLabelService),
+    comments: makeClient(CommentService),
+    taskDependencies: makeClient(TaskDependencyService),
+    notifications: makeClient(NotificationService),
+    acceptanceCriteria: makeClient(AcceptanceCriterionService),
+    initiatives: makeClient(InitiativeService),
+    docTemplates: makeClient(DocTemplateService),
+    taskDocPages: makeClient(TaskDocPageService),
+    milestoneDocPages: makeClient(MilestoneDocPageService),
+  };
+}
+
+/** The MCP server's clients, stamped `mcp`. */
 export function getClients(): ApiClients {
   if (!cachedClients) {
-    cachedClients = {
-      projects: makeClient(ProjectService),
-      tasks: makeClient(TaskService),
-      boards: makeClient(BoardService),
-      boardColumns: makeClient(BoardColumnService),
-      cycles: makeClient(CycleService),
-      docSpaces: makeClient(DocSpaceService),
-      docPages: makeClient(DocPageService),
-      docPageVersions: makeClient(DocPageVersionService),
-      taskTypes: makeClient(TaskTypeService),
-      taskPriorities: makeClient(TaskPriorityService),
-      users: makeClient(UserService),
-      vcsIntegrations: makeClient(VCSIntegrationService),
-      milestones: makeClient(MilestoneService),
-      milestoneTasks: makeClient(MilestoneTaskService),
-      labels: makeClient(LabelService),
-      taskLabels: makeClient(TaskLabelService),
-      comments: makeClient(CommentService),
-      taskDependencies: makeClient(TaskDependencyService),
-      notifications: makeClient(NotificationService),
-      acceptanceCriteria: makeClient(AcceptanceCriterionService),
-      initiatives: makeClient(InitiativeService),
-      docTemplates: makeClient(DocTemplateService),
-      taskDocPages: makeClient(TaskDocPageService),
-      milestoneDocPages: makeClient(MilestoneDocPageService),
-    };
+    cachedClients = createClients();
   }
   return cachedClients;
 }

package/src/client/marker.ts

@@ -0,0 +1,17 @@
+import type { Interceptor } from "@connectrpc/connect";
+
+/** Request header that names the calling client. The backend reads it as the client origin: an
+ * automation client (the MCP server, the `opsee` CLI) using a user's token must not be
+ * self-skipped on that user's board, and Run Record events it appends are marked agent-authored. */
+export const CLIENT_HEADER = "X-Opsee-Client";
+
+/** What the MCP server sends; the CLI sends `cli`. */
+export const MCP_CLIENT_MARKER = "mcp";
+
+/** Stamps every request with the given client marker. */
+export function clientInterceptor(marker: string): Interceptor {
+  return (next) => async (req) => {
+    req.header.set(CLIENT_HEADER, marker);
+    return await next(req);
+  };
+}

package/src/server.ts

@@ -18,6 +18,7 @@ import { registerInitiativeTools } from "./tools/initiatives.js";
 import { registerDocSpaceWriteTools } from "./tools/doc-spaces.js";
 import { registerDocTemplateTools } from "./tools/doc-templates.js";
 import { registerDocLinkTools } from "./tools/doc-links.js";
+import { registerForemanTools } from "./tools/foreman.js";
 import { compactToolDefinitions } from "./utils/tool-schema.js";
 
 export function createServer(clientFactory?: () => ApiClients): McpServer {
@@ -46,6 +47,7 @@ export function createServer(clientFactory?: () => ApiClients): McpServer {
   registerDocSpaceWriteTools(server, factory);
   registerDocTemplateTools(server, factory);
   registerDocLinkTools(server, factory);
+  registerForemanTools(server, factory);
 
   compactToolDefinitions(server);
 

package/src/tools/foreman.ts

@@ -0,0 +1,371 @@
+/**
+ * The two tools that join a planning session to the Foreman (spec stories 70 and 71).
+ *
+ * `opsee_read_run_record` reads what the Foreman wrote overnight, so a morning session can ask what
+ * happened before it re-plans. `opsee_file_defect` writes the other way: an attended session that
+ * verified something by hand files its finding as the same Task the unattended Verifier would have
+ * filed, so the ordinary dispatch loop schedules the fix.
+ *
+ * The Defect Task's shape is not defined here. It comes from ../utils/defect.js, which the CLI's
+ * own filer imports too: one implementation, so the two are indistinguishable to the Worker that
+ * picks the Task up and to the Foreman's own duplicate check, which reads the `[defect:<key>]`
+ * token this tool writes.
+ */
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { defaultPagination, overridePagination } from "../client/api.js";
+import { TaskDependencyType, type Task } from "../../gen/api/v1/models_pb.js";
+import type { RunEvent } from "../../gen/api/v1/initiative_pb.js";
+import { formatError } from "../utils/format.js";
+import { EVENT_BUDGET, eventTime, formatRunEvent, formatRunRecord, RUN_EVENT_KINDS, type RunRecordPage } from "../utils/format/run-record.js";
+import {
+  ATTENDED_AUTHOR,
+  DEFECT_COMMENT_MARKER,
+  DEFECT_LABEL,
+  DEFECT_TASK_TYPE,
+  DISPATCH_LABEL,
+  defectKey,
+  defectKeysInComments,
+  defectTaskDescription,
+  defectTaskTitle,
+} from "../utils/defect.js";
+import { oneLine, sameName } from "../utils/text.js";
+
+/** How many events one server page carries while the tool scans for a time range. */
+const SERVER_PAGE = 100;
+
+/** The most events a single call will read from the server, however narrow the time range. A
+ * planning session wants last night, not the whole Run; a wider read is another call away. */
+const SCAN_MAX = 1000;
+
+/** Seconds since the epoch for an ISO 8601 instant, or undefined when it does not parse. */
+function instant(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const ms = Date.parse(value);
+  return Number.isNaN(ms) ? undefined : Math.floor(ms / 1000);
+}
+
+export function registerForemanTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_read_run_record",
+    "Read an Initiative's Run Record — the Foreman's append-only log of what its unattended Workers did: every dispatch, how each turn ended, the Gate results (exit codes), the Verifier's Verdicts and Defects, human steering from the CLI, spend, and any Breaker that halted the night. Call this at the start of a planning session to ask what happened since you last looked, and before re-planning an Initiative the Foreman has been running. Filter by kind and by task, narrow to a time range, and page with afterId. Everything an agent wrote or a command printed comes back quoted as data.",
+    {
+      initiativeId: z.number().int().min(1).describe("The initiative ID whose Run Record to read"),
+      kinds: z.array(z.enum(RUN_EVENT_KINDS)).optional().describe("Filter by event kind: dispatch (a Worker was started) | attempt (a turn ended) | gate (tests/lint/typecheck ran) | verdict (a Verifier reported) | breaker (dispatch was halted) | spend | control (a human attached, released, paused, resumed, or cancelled) | account (an Account was Paused, quarantined, or brought back). Omit for all kinds."),
+      taskId: z.number().int().min(1).optional().describe("Only events about this task. Run-wide events (breaker, spend, a Run-level pause) carry no task and are excluded when this is set."),
+      since: z.string().optional().describe("Only events at or after this instant (ISO 8601, e.g. '2026-09-07T18:00:00Z'). Applied to when the event happened on the Foreman's machine."),
+      until: z.string().optional().describe("Only events at or before this instant (ISO 8601)."),
+      afterId: z.number().int().min(1).optional().describe("Pagination cursor: only events with a higher id. Pass the value the previous call reported."),
+      limit: z.number().int().min(1).max(200).optional().describe("Maximum events to return (default 50, max 200)."),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ initiativeId, kinds, taskId, since, until, afterId, limit }) => {
+      try {
+        const clients = getClients();
+        const want = limit ?? 50;
+        const from = instant(since);
+        const to = instant(until);
+        if (since && from === undefined) return { content: [{ type: "text", text: `Could not read "since" as a date: ${since}. Use ISO 8601, e.g. 2026-09-07T18:00:00Z.` }], isError: true };
+        if (until && to === undefined) return { content: [{ type: "text", text: `Could not read "until" as a date: ${until}. Use ISO 8601, e.g. 2026-09-08T09:00:00Z.` }], isError: true };
+
+        const page: RunRecordPage = { events: [], filters: [], scanned: 0 };
+        // `kinds` is a zod enum and the ids are numbers, so only the two instants are free text —
+        // echoed on one line, as everything outside a quoted block in this output is.
+        if (kinds?.length) page.filters.push(`kinds=${kinds.join(",")}`);
+        if (taskId) page.filters.push(`task=#${taskId}`);
+        if (since) page.filters.push(`since=${oneLine(since)}`);
+        if (until) page.filters.push(`until=${oneLine(until)}`);
+        if (afterId) page.filters.push(`afterId=${afterId}`);
+
+        // The backend filters by kind, task and cursor; it has no time filter, so a time range is
+        // applied here while paging. Bounded by SCAN_MAX so a narrow range over a long Run cannot
+        // walk the whole Record in one call, and by EVENT_BUDGET so one call cannot return
+        // megabytes into a planning session's context.
+        let cursor = afterId;
+        let atEnd = false;
+        let used = 0;
+        scan: while (page.events.length < want && page.scanned < SCAN_MAX) {
+          const res = await clients.initiatives.getRunEvents({
+            initiativeId,
+            pagination: defaultPagination(1, SERVER_PAGE),
+            kinds: kinds ?? [],
+            taskId,
+            afterId: cursor,
+          });
+          page.run ??= res.run;
+          if (res.events.length === 0) {
+            atEnd = true;
+            break;
+          }
+          for (const event of res.events) {
+            // Every exit below leaves `scanned` and `cursor` covering exactly what this page
+            // consumed, so the next call resumes at the first event the caller has not been shown.
+            if (page.events.length >= want) break scan;
+            const at = eventTime(event);
+            // The Record is appended in id order, so the first event past `until` is the end of the
+            // range: without this a caller with an `until` in the past walks the whole Record a
+            // page at a time, discarding all of it.
+            if (to !== undefined && at !== undefined && at > to) {
+              page.stoppedPastUntil = event.id;
+              break scan;
+            }
+            if (from !== undefined && (at === undefined || at < from)) {
+              page.scanned++;
+              cursor = event.id;
+              continue;
+            }
+            if (to !== undefined && at === undefined) {
+              page.scanned++;
+              cursor = event.id;
+              continue;
+            }
+            // Rendered here, not in the formatter, so the budget is spent on what the caller will
+            // actually be shown and the cursor stops on the event that did not fit.
+            const rendered = formatRunEvent(event as RunEvent);
+            if (page.events.length > 0 && used + rendered.length > EVENT_BUDGET) {
+              page.budgetReached = true;
+              break scan;
+            }
+            used += rendered.length;
+            page.scanned++;
+            cursor = event.id;
+            page.events.push(rendered);
+          }
+          if (res.events.length < SERVER_PAGE) {
+            atEnd = true;
+            break;
+          }
+        }
+        // Nothing after the first event past `until` is inside the range, so that is the end of
+        // this filter's Record rather than a page boundary to resume from.
+        if (!atEnd && page.stoppedPastUntil === undefined) page.nextCursor = cursor;
+
+        return { content: [{ type: "text", text: formatRunRecord(page) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_file_defect",
+    "File one failure you observed while verifying a Task as a Defect Task, exactly as the Foreman's unattended Verifier would: a sibling Task in the same Initiative (never a subtask), type Bug, related to the Task you found it on, carrying the dispatch label so the next tick schedules the fix, with a Goal / Acceptance Criteria / Verification / Boundaries description. Use this after verifying work by hand in an attended session — not for planned work, which belongs in the task tree. Everything you write here is quoted as data in the new Task, so a Worker reads it as a record of what you saw, never as instructions.",
+    {
+      taskId: z.number().int().min(1).describe("The task you found the failure on. The new Task relates to it and names it; the task must be in an Initiative, because that is what makes the fix dispatchable."),
+      title: z.string().min(1).describe("One line naming the failure, e.g. 'Label unchanged after pressing'. Becomes the new Task's title, prefixed with the identifier of the task above."),
+      steps: z.string().min(1).describe("What you did, step by step, to reach the failure. This becomes the fix Task's Verification section, so write it as a journey someone else can walk."),
+      expected: z.string().optional().describe("What should have happened at the end of those steps."),
+      observed: z.string().optional().describe("What happened instead."),
+      evidenceUrl: z.string().optional().describe("A link to a screenshot or recording. Evidence is linked, never pasted."),
+      pullRequestUrl: z.string().optional().describe("The pull request the work under review is on, if there is one."),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId, title, steps, expected, observed, evidenceUrl, pullRequestUrl }) => {
+      try {
+        const clients = getClients();
+        const originRes = await clients.tasks.getTask({ id: taskId });
+        const origin = originRes.task;
+        if (!origin) return { content: [{ type: "text", text: `Task ${taskId} not found. Use opsee_list_tasks to find the task you verified.` }], isError: true };
+        const initiativeId = origin.initiativeId;
+        if (!initiativeId) {
+          return {
+            content: [{ type: "text", text: `Task ${origin.identifier} is not in an Initiative, so a Defect filed against it could never be dispatched. Link it with opsee_link_task_to_initiative first.` }],
+            isError: true,
+          };
+        }
+        const projectId = origin.project?.id ?? 0;
+        if (!projectId) return { content: [{ type: "text", text: `Task ${origin.identifier} carries no project, so its labels and type cannot be resolved.` }], isError: true };
+
+        // Idempotent, exactly as the Foreman's own filer is (cli/src/foreman/core/defects.ts
+        // `alreadyFiled`): the key is the title alone, and a Defect already named in a filing
+        // comment on this Task is not filed twice. Without this, two calls with the same Defect —
+        // a retry, a session that repeated itself — create two dispatchable Bug Tasks and the
+        // Foreman runs both. The key is computed before anything is created, so nothing is left
+        // half-written when the answer is "already filed".
+        const key = defectKey(title);
+        const filed = await clients.comments.getComments({ taskId: origin.id, pagination: overridePagination() });
+        const already = defectKeysInComments((filed.comments ?? []).map((c) => c.content ?? ""));
+        if (already.has(key)) {
+          return {
+            content: [{
+              type: "text",
+              text: [
+                `Already filed: a Defect with this title is recorded on ${origin.identifier} as [defect:${key}], so nothing was created.`,
+                "",
+                `The key is the title alone, so the same failure seen twice files one fix Task. Look for the Bug Task related to ${origin.identifier} — opsee_list_tasks with the "${DEFECT_LABEL}" label finds it — or file this under a different title if it really is a different failure.`,
+              ].join("\n"),
+            }],
+          };
+        }
+
+        const defect = { title, steps, expected: expected ?? "", observed: observed ?? "" };
+        const description = defectTaskDescription({
+          origin: { identifier: origin.identifier, title: origin.title },
+          defect,
+          evidence: evidenceUrl ? { url: evidenceUrl } : undefined,
+          pullRequestUrl,
+          author: ATTENDED_AUTHOR,
+        });
+
+        // Both labels must exist in the project before a Task can carry them.
+        const labelIds = await Promise.all([DISPATCH_LABEL, DEFECT_LABEL].map((name) => ensureLabel(clients, projectId, name)));
+
+        // Every field below is picked exactly as OpseeTrackerAdapter.createTask picks it for the
+        // Foreman's own filer (cli/src/foreman/opsee-tracker-adapter.ts `projectDefaults` and
+        // `pickNamed`), because a Defect filed here and a Defect filed by the unattended Verifier
+        // must be indistinguishable on the board: the active board else the first; the active
+        // columns in display order, the `todo` one else the first; the "Bug" type else the first;
+        // and the project's first priority — the adapter asks for no priority by name, and
+        // `pickNamed` with no name is `options[0]`. Not the origin's priority: that would make a
+        // Defect filed from a session sort differently from the same Defect filed by a Verdict.
+        const [boards, types, priorities] = await Promise.all([
+          clients.boards.getBoards({ projectId, pagination: overridePagination() }),
+          clients.taskTypes.getTaskTypes({ projectId, pagination: overridePagination() }),
+          clients.taskPriorities.getTaskPriorities({ projectId, pagination: overridePagination() }),
+        ]);
+        const board = boards.boards.find((b) => b.isActive) ?? boards.boards[0];
+        if (!board) return { content: [{ type: "text", text: `Project ${projectId} has no board, so a Task cannot be created in it.` }], isError: true };
+        const columnsRes = await clients.boardColumns.getBoardColumns({ boardId: board.id, pagination: overridePagination() });
+        const columns = (columnsRes.boardColumns ?? []).filter((c) => c.isActive).sort((a, b) => a.displayOrder - b.displayOrder);
+        const landing = columns.find((c) => c.lifecycleState === "todo") ?? columns[0];
+        if (!landing) return { content: [{ type: "text", text: `Board ${board.id} has no active columns, so a Task cannot be created in it.` }], isError: true };
+        const bug = types.taskTypes.find((t) => sameName(t.name, DEFECT_TASK_TYPE)) ?? types.taskTypes[0];
+        if (!bug) return { content: [{ type: "text", text: `Project ${projectId} has no task types, so a Task cannot be created in it.` }], isError: true };
+        const priority = priorities.taskPriorities[0];
+        if (!priority) return { content: [{ type: "text", text: `Project ${projectId} has no priorities, so a Task cannot be created in it.` }], isError: true };
+
+        // The Foreman's filer reports the Task as created by whoever's token it runs under
+        // (`OpseeTrackerAdapter.me`), never by the origin's reporter; so does this.
+        const meRes = await clients.users.getMe({});
+        if (!meRes.user) return { content: [{ type: "text", text: "The backend returned no user for this token, so the Defect Task would have no reporter. Check the MCP server's credentials." }], isError: true };
+
+        const created = await clients.tasks.addTask({
+          projectId,
+          title: defectTaskTitle(origin.identifier, defect),
+          description,
+          boardId: board.id,
+          boardColumnId: landing.id,
+          taskTypeId: bug.id,
+          taskPriorityId: priority.id,
+          reporterUserId: meRes.user.id,
+          displayOrder: "",
+          aiModeEnabled: false,
+          repositoryIds: [],
+          labelIds,
+        });
+        const task = created.task;
+        if (!task) return { content: [{ type: "text", text: "Failed to create the Defect task. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+
+        // AddTask cannot place a Task in an Initiative and an edge needs the new id, so this is two
+        // more calls. A Defect left outside its Initiative is not dispatchable and a Defect with no
+        // edge is an orphan, so a failure here is reported with the id rather than swallowed.
+        const wired: string[] = [];
+        try {
+          await linkToInitiative(clients, task, initiativeId);
+          wired.push(`placed in initiative ${initiativeId}`);
+          await clients.taskDependencies.addTaskDependency({ fromTaskId: task.id, toTaskId: origin.id, type: TaskDependencyType.RELATES_TO });
+          wired.push(`related to ${origin.identifier}`);
+        } catch (error) {
+          return {
+            content: [{ type: "text", text: `Created ${task.identifier} (id ${task.id}) but could not finish wiring it (${wired.join("; ") || "nothing wired"}): ${formatError(error)}\n\nFinish it by hand with opsee_link_task_to_initiative and opsee_create_task_dependency, or delete it with opsee_delete_task.` }],
+            isError: true,
+          };
+        }
+
+        // The same marker and token the Foreman's filer writes, so its duplicate check reads this
+        // Defect back and does not file it a second time from a Verdict that saw the same thing.
+        const comment = [
+          DEFECT_COMMENT_MARKER,
+          "",
+          `1 Defect from an attended verification pass on ${origin.identifier} is now a Task of this Initiative, related to this one and labelled "${DISPATCH_LABEL}", so the next tick dispatches it.`,
+          "",
+          `- [defect:${key}] ${task.identifier}: ${oneLine(title)}`,
+        ].join("\n");
+        let commented = true;
+        try {
+          await clients.comments.addComment({ taskId: origin.id, content: comment, isInternal: false });
+        } catch {
+          commented = false;
+        }
+
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `Defect filed as ${task.identifier} (id ${task.id}).`,
+              `  Title: ${task.title}`,
+              `  Type: ${bug.name} · Column: ${landing.name} · Labels: ${DISPATCH_LABEL}, ${DEFECT_LABEL}`,
+              `  ${wired.join(" · ")} · key [defect:${key}]`,
+              commented
+                ? `  A comment naming it was left on ${origin.identifier}.`
+                : `  The comment on ${origin.identifier} could not be posted; the Task itself is the record. Consider adding one with opsee_add_comment.`,
+              "",
+              `${origin.identifier} was not moved or edited: it keeps its column, its labels and its pull request.`,
+            ].join("\n"),
+          }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}
+
+/** The id of a project label by name, creating it when the project has no active one. Matched the
+ * way the backend matches the dispatch label when it decides what is Ready (`LOWER(name) =
+ * LOWER(?) AND is_active`, backend/repository/run.go) and the way the Foreman's own filer matches
+ * it (`OpseeTrackerAdapter.ensureLabel`).
+ *
+ * `isActive` is not a detail: a deactivated "ready-for-agent" is a label `GetReadyTasks` will never
+ * match, so returning its id would file a Defect that is never dispatched while the tool reports
+ * that the next tick will pick it up. Whitespace is significant for the same reason — the backend
+ * does not trim, so `"ready-for-agent "` is a different label there and must be here too. */
+async function ensureLabel(clients: ApiClients, projectId: number, name: string): Promise<number> {
+  const res = await clients.labels.getLabels({ projectId, pagination: overridePagination() });
+  const found = res.labels.find((l) => l.isActive && sameName(l.name, name));
+  if (found) return found.id;
+  const created = await clients.labels.addLabel({ projectId, name, isActive: true });
+  if (!created.label) throw new Error(`Creating the "${name}" label in project ${projectId} returned no label`);
+  return created.label.id;
+}
+
+/** EditTask validates the whole Task, so placing one in an Initiative resends what the backend
+ * already has. Same shape as opsee_link_task_to_initiative.
+ *
+ * Every id falls back to the Task's own flat field, exactly as `OpseeTrackerAdapter.editTask` does:
+ * `TaskRepository.Get` preloads Project, TaskType, TaskPriority, ReporterUser and BoardColumn but
+ * not Board, and AddTask builds its response from that Get, so `task.board` is undefined on every
+ * real call and `task.board?.id ?? 0` would send boardId 0. It is the generated `Task` rather than
+ * a structural type so the compiler can see the flat fields — the hand-rolled type is what let
+ * that through. */
+async function linkToInitiative(clients: ApiClients, task: Task, initiativeId: number): Promise<void> {
+  await clients.tasks.editTask({
+    id: task.id,
+    identifier: task.identifier,
+    title: task.title,
+    description: task.description,
+    displayOrder: task.displayOrder,
+    storyPoints: task.storyPoints,
+    estimatedHours: task.estimatedHours,
+    actualHours: task.actualHours,
+    dueDate: task.dueDate,
+    aiModeEnabled: task.aiModeEnabled,
+    metadataJson: task.metadataJson,
+    boardId: task.board?.id ?? task.boardId,
+    boardColumnId: task.boardColumn?.id ?? task.boardColumnId,
+    projectId: task.project?.id ?? task.projectId,
+    taskTypeId: task.taskType?.id ?? task.taskTypeId,
+    taskPriorityId: task.taskPriority?.id ?? task.taskPriorityId,
+    reporterUserId: task.reporterUser?.id ?? task.reporterUserId,
+    assignedUserId: task.assignedUser?.id ?? task.assignedUserId,
+    cycleId: task.cycle?.id ?? task.cycleId,
+    milestoneId: task.milestoneId,
+    parentTaskId: task.parentTaskId,
+    repositoryIds: task.taskRepositories?.map((r) => r.id) ?? [],
+    initiativeId,
+  });
+}