terramend 0.2.0

package/src/mcp/selectMode.test.ts

@@ -0,0 +1,210 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { SelectModeTool } from "#app/mcp/selectMode";
+import type { ToolContext } from "#app/mcp/server";
+import type { Mode } from "#app/modes";
+import type { ToolState } from "#app/toolState";
+import { apiFetch } from "#app/utils/apiFetch";
+
+vi.mock("#app/utils/apiFetch", () => ({
+  apiFetch: vi.fn(),
+}));
+
+const apiFetchMock = vi.mocked(apiFetch);
+
+type ToolResultShape = { content: [{ type: "text"; text: string }]; isError?: boolean };
+
+async function runTool(t: { execute?: unknown }, params: unknown): Promise<ToolResultShape> {
+  const exec = t.execute as (p: unknown, c: unknown) => Promise<ToolResultShape>;
+  return exec(params, {});
+}
+
+const MODES: Mode[] = [
+  { name: "Build", description: "implement changes", prompt: "BUILD-PROMPT" },
+  { name: "Plan", description: "plan work", prompt: "PLAN-PROMPT" },
+  { name: "Review", description: "review a PR", prompt: "REVIEW-PROMPT" },
+  { name: "IncrementalReview", description: "review the delta", prompt: "INCR-PROMPT" },
+  { name: "Fix", description: "fix CI", prompt: undefined },
+];
+
+function makeCtx(overrides?: {
+  toolState?: Partial<ToolState>;
+  modeInstructions?: Record<string, string>;
+  issueNumber?: number;
+  githubInstallationToken?: string;
+}): { ctx: ToolContext; toolState: ToolState } {
+  const toolState = { ...overrides?.toolState } as ToolState;
+  const ctx = {
+    agentId: "claude",
+    repo: { owner: "octo", name: "repo" },
+    payload: { event: { issue_number: overrides?.issueNumber } },
+    modes: MODES,
+    modeInstructions: overrides?.modeInstructions ?? {},
+    toolState,
+    githubInstallationToken: overrides?.githubInstallationToken ?? "ghs_token",
+  } as unknown as ToolContext;
+  return { ctx, toolState };
+}
+
+function planCommentResponse(
+  body: { commentId: number; body: string } | { error: string },
+  ok = true,
+) {
+  return { ok, json: async () => body } as unknown as Response;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  apiFetchMock.mockResolvedValue(planCommentResponse({ error: "not found" }, false));
+});
+
+describe("SelectModeTool", () => {
+  it("rejects a second selection once a mode is chosen", async () => {
+    const { ctx } = makeCtx({ toolState: { selectedMode: "Build" } });
+    const result = await runTool(SelectModeTool(ctx), { mode: "Review" });
+
+    expect(result.content[0].text).toContain("mode already selected");
+    expect(result.content[0].text).toContain("Build");
+  });
+
+  it("lists the available modes when the requested one is unknown", async () => {
+    const { ctx, toolState } = makeCtx();
+    const result = await runTool(SelectModeTool(ctx), { mode: "Nonsense" });
+
+    expect(result.content[0].text).toContain("Nonsense");
+    expect(result.content[0].text).toContain("not found. available modes:");
+    expect(result.content[0].text).toContain("Build, Plan, Review, IncrementalReview, Fix");
+    expect(toolState.selectedMode).toBeUndefined();
+  });
+
+  it("resolves the mode case-insensitively and records the selection", async () => {
+    const { ctx, toolState } = makeCtx();
+    const result = await runTool(SelectModeTool(ctx), { mode: "review" });
+
+    expect(result.isError).toBeUndefined();
+    expect(toolState.selectedMode).toBe("Review");
+    expect(result.content[0].text).toContain("REVIEW-PROMPT");
+  });
+
+  it("joins the hardcoded prompt with the user's mode instructions", async () => {
+    const { ctx } = makeCtx({ modeInstructions: { Build: "USER-BUILD-RULES" } });
+    const result = await runTool(SelectModeTool(ctx), { mode: "Build" });
+
+    expect(result.content[0].text).toContain("BUILD-PROMPT");
+    expect(result.content[0].text).toContain("USER-BUILD-RULES");
+  });
+
+  it("Fix inherits Build's user instructions (no prompt of its own)", async () => {
+    const { ctx } = makeCtx({ modeInstructions: { Build: "USER-BUILD-RULES" } });
+    const result = await runTool(SelectModeTool(ctx), { mode: "Fix" });
+
+    expect(result.content[0].text).toContain("modeName: Fix");
+    expect(result.content[0].text).toContain("USER-BUILD-RULES");
+    expect(result.content[0].text).not.toContain("BUILD-PROMPT");
+  });
+
+  it("IncrementalReview inherits Review's user instructions", async () => {
+    const { ctx } = makeCtx({ modeInstructions: { Review: "USER-REVIEW-RULES" } });
+    const result = await runTool(SelectModeTool(ctx), { mode: "IncrementalReview" });
+
+    expect(result.content[0].text).toContain("INCR-PROMPT");
+    expect(result.content[0].text).toContain("USER-REVIEW-RULES");
+  });
+
+  describe("Plan mode with an existing plan comment", () => {
+    it("returns PlanEdit guidance plus the previous plan body", async () => {
+      apiFetchMock.mockResolvedValue(planCommentResponse({ commentId: 88, body: "OLD-PLAN-BODY" }));
+      const { ctx, toolState } = makeCtx();
+      const result = await runTool(SelectModeTool(ctx), { mode: "Plan", issue_number: 42 });
+
+      expect(apiFetchMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          path: "/api/repo/octo/repo/issue/42/plan-comment",
+          headers: { authorization: "Bearer ghs_token" },
+        }),
+      );
+      expect(toolState.existingPlanCommentId).toBe(88);
+      expect(toolState.previousPlanBody).toBe("OLD-PLAN-BODY");
+      expect(result.content[0].text).toContain("editing existing plan");
+      expect(result.content[0].text).toContain("OLD-PLAN-BODY");
+      expect(result.content[0].text).toContain("mcp__"); // claude-formatted tool refs
+    });
+
+    it("falls back to the event's issue number when none is passed", async () => {
+      apiFetchMock.mockResolvedValue(planCommentResponse({ commentId: 9, body: "B" }));
+      const { ctx } = makeCtx({ issueNumber: 7 });
+      await runTool(SelectModeTool(ctx), { mode: "Plan" });
+
+      expect(apiFetchMock).toHaveBeenCalledWith(
+        expect.objectContaining({ path: "/api/repo/octo/repo/issue/7/plan-comment" }),
+      );
+    });
+
+    it("returns plain Plan guidance when the API has no plan comment", async () => {
+      const { ctx, toolState } = makeCtx();
+      const result = await runTool(SelectModeTool(ctx), { mode: "Plan", issue_number: 42 });
+
+      expect(toolState.existingPlanCommentId).toBeUndefined();
+      expect(result.content[0].text).toContain("PLAN-PROMPT");
+      expect(result.content[0].text).not.toContain("editing existing plan");
+    });
+
+    it("ignores an OK response whose body is an error payload", async () => {
+      apiFetchMock.mockResolvedValue(planCommentResponse({ error: "no plan yet" }, true));
+      const { ctx, toolState } = makeCtx();
+      const result = await runTool(SelectModeTool(ctx), { mode: "Plan", issue_number: 42 });
+
+      expect(toolState.existingPlanCommentId).toBeUndefined();
+      expect(result.content[0].text).toContain("PLAN-PROMPT");
+    });
+
+    it("treats an API error as no existing plan comment", async () => {
+      apiFetchMock.mockRejectedValue(new Error("network down"));
+      const { ctx } = makeCtx();
+      const result = await runTool(SelectModeTool(ctx), { mode: "Plan", issue_number: 42 });
+
+      expect(result.isError).toBeUndefined();
+      expect(result.content[0].text).toContain("PLAN-PROMPT");
+    });
+
+    it("skips the lookup without a GitHub installation token", async () => {
+      const { ctx } = makeCtx({ githubInstallationToken: "" });
+      const result = await runTool(SelectModeTool(ctx), { mode: "Plan", issue_number: 42 });
+
+      expect(apiFetchMock).not.toHaveBeenCalled();
+      expect(result.content[0].text).toContain("PLAN-PROMPT");
+    });
+
+    it("skips the lookup when no issue number is available at all", async () => {
+      const { ctx } = makeCtx();
+      const result = await runTool(SelectModeTool(ctx), { mode: "Plan" });
+
+      expect(apiFetchMock).not.toHaveBeenCalled();
+      expect(result.content[0].text).toContain("PLAN-PROMPT");
+    });
+  });
+
+  describe("PR summary snapshot addendum", () => {
+    it("appends the snapshot step for Review when a summary file is set", async () => {
+      const { ctx } = makeCtx({ toolState: { summaryFilePath: "/tmp/summary.md" } });
+      const result = await runTool(SelectModeTool(ctx), { mode: "Review" });
+
+      expect(result.content[0].text).toContain("PR summary snapshot");
+      expect(result.content[0].text).toContain("/tmp/summary.md");
+      expect(result.content[0].text).toContain("REVIEW-PROMPT");
+    });
+
+    it("omits the addendum for Review without a summary file", async () => {
+      const { ctx } = makeCtx();
+      const result = await runTool(SelectModeTool(ctx), { mode: "Review" });
+
+      expect(result.content[0].text).not.toContain("PR summary snapshot");
+    });
+
+    it("never appends the addendum for non-summary modes", async () => {
+      const { ctx } = makeCtx({ toolState: { summaryFilePath: "/tmp/summary.md" } });
+      const result = await runTool(SelectModeTool(ctx), { mode: "Build" });
+
+      expect(result.content[0].text).not.toContain("PR summary snapshot");
+    });
+  });
+});

package/src/mcp/selectMode.ts

@@ -0,0 +1,181 @@
+import { type } from "arktype";
+import { formatMcpToolRef } from "#app/external";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool } from "#app/mcp/shared";
+import type { Mode } from "#app/modes";
+import { apiFetch } from "#app/utils/apiFetch";
+
+export const SelectModeParams = type({
+  mode: type.string.describe(
+    "the name of the mode to select (e.g., 'Build', 'Plan', 'Review', 'IncrementalReview', 'Fix', 'AddressReviews', 'Task', 'ResolveConflicts')",
+  ),
+  "issue_number?": type("number").describe(
+    "optional issue number; when provided with Plan mode, used to look up an existing plan comment for this issue (edit vs create)",
+  ),
+});
+
+function resolveMode(modes: Mode[], modeName: string): Mode | null {
+  return modes.find((m) => m.name.toLowerCase() === modeName.toLowerCase()) ?? null;
+}
+
+function buildModeOverrides(t: (name: string) => string): Record<string, string> {
+  return {
+    PlanEdit: `### Checklist (editing existing plan)
+
+An existing plan comment was found for this issue. Update that comment with the revised plan — do not create a new plan comment.
+
+1. **task list**: create your task list for this run as your first action.
+2. Use \`previousPlanBody\` from this response as the plan to revise; do not call \`get_issue\` or \`get_issue_comments\`.
+3. Revise the plan based on the user's request:
+   - incorporate the current plan (\`previousPlanBody\`) and the user's revision request
+   - gather relevant codebase context (file paths, architecture notes from AGENTS.md)
+   - produce a structured plan with clear milestones
+4. Call \`${t("report_progress")}\` with the full revised plan text and \`{ target_plan_comment: true }\` so it updates the existing plan comment (not the progress comment).
+5. Then post a short note to the progress comment (e.g. "Plan has been updated in the comment above.") via \`${t("report_progress")}\` so it is not left as "Leaping...".`,
+  };
+}
+
+type OrchestratorGuidance = {
+  modeName: string;
+  description: string;
+  orchestratorGuidance: string;
+};
+
+// IncrementalReview inherits Review's user instructions, Fix inherits Build's
+const modeInstructionParent: Record<string, string> = {
+  IncrementalReview: "Review",
+  Fix: "Build",
+};
+
+function buildOrchestratorGuidance(
+  ctx: ToolContext,
+  mode: Mode,
+  overrideGuidance?: string,
+): OrchestratorGuidance {
+  const hardcoded = overrideGuidance ?? mode.prompt ?? "";
+  const lookupKey = modeInstructionParent[mode.name] ?? mode.name;
+  const userInstructions = ctx.modeInstructions[lookupKey] ?? "";
+  const guidance = [hardcoded, userInstructions].filter(Boolean).join("\n\n");
+  return {
+    modeName: mode.name,
+    description: mode.description,
+    orchestratorGuidance: guidance,
+  };
+}
+
+// matches the API response for /repo/[owner]/[repo]/issue/[issueNumber]/plan-comment
+export type PlanCommentResponsePayload = { error: string } | { commentId: number; body: string };
+
+// IMPORTANT: this route authenticates via GitHub installation token (getEnrichedRepo),
+// NOT the Terramend API JWT (ctx.apiToken). use ctx.githubInstallationToken here.
+// see wiki/api-auth.md for the two auth patterns.
+async function fetchExistingPlanComment(
+  ctx: ToolContext,
+  issueNumber: number,
+): Promise<Extract<PlanCommentResponsePayload, { commentId: number }> | null> {
+  if (!ctx.githubInstallationToken) return null;
+  try {
+    const response = await apiFetch({
+      path: `/api/repo/${ctx.repo.owner}/${ctx.repo.name}/issue/${issueNumber}/plan-comment`,
+      method: "GET",
+      headers: { authorization: `Bearer ${ctx.githubInstallationToken}` },
+      signal: AbortSignal.timeout(10_000),
+    });
+    const data = (await response.json()) as PlanCommentResponsePayload;
+    return response.ok && "commentId" in data ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+const SUMMARY_MODES = new Set(["Review", "IncrementalReview", "Task"]);
+
+/** modes that gain the PR summary edit step when toolState.summaryFilePath is set.
+ *
+ * NOTE: this snapshot is an internal artifact consumed by future agent runs. it is
+ * deliberately NOT shaped by user-supplied summary instructions — those would warp
+ * the durable agent context. user-facing summarization (e.g. the review body's
+ * "Reviewed changes" section) is governed by review-mode prompts and review
+ * instructions, separately from this snapshot. */
+function buildSummaryAddendum(t: (name: string) => string, ctx: ToolContext): string {
+  const filePath = ctx.toolState.summaryFilePath;
+  if (!filePath) return "";
+  return `### PR summary snapshot — required step
+
+A rolling PR summary lives at \`${filePath}\`. It is your durable cross-run agent context — a functional summary of what this PR does, the subsystems and files it touches, the material behavior of its changes, and any risks or open questions worth carrying forward. It is NOT a chronological log of past review runs; commit-level history can already be reconstructed from \`${t("list_pull_request_reviews")}\`.
+
+How to use it:
+
+- read \`${filePath}\` at the START of the run, alongside the diff. it represents what previous agent runs already understood about this PR — absorb it before picking lenses or crafting subagent dispatch prompts. if it's a fresh seed (file is one or two lines), this is a first review and you'll be filling it in from the diff.
+- let the snapshot inform triage and dispatch. when it already tracks a risk, your lens prompts to subagents are stronger when they reference that context (e.g. "the JSDoc explicitly scopes to code points — do not flag grapheme-cluster issues" if the snapshot already documents that contract). when something the snapshot tracks is now resolved by new commits, note that. when new commits introduce something the snapshot doesn't yet describe, that's exactly where your fan-out should focus.
+- update the file in place to reflect the PR's CURRENT state. revise stale claims, drop resolved risks, add new behavior or risks. accuracy over breadth — every claim must be grounded in the diff. write for the next agent run, not for a human.
+- structure however serves THIS PR. there is no required section template. a refactor might organize by renamed export and call-site impact; a feature by capability; a billing change by money path. a compact note of which commit ranges have been reviewed should always be present so future runs scope correctly, but the rest is your call. when the structure works across runs, keep it stable so range-diffs are clean; when the PR's character changes (e.g. scope expands), reshape.
+
+Do NOT call \`${t("create_issue_comment")}\` for the summary — the server reads this file at end-of-run and persists it. The file edit is mandatory regardless of whether a review is submitted; the snapshot feeds the next run.`;
+}
+
+export function SelectModeTool(ctx: ToolContext) {
+  const t = (name: string) => formatMcpToolRef(ctx.agentId, name);
+  const overrides = buildModeOverrides(t);
+
+  return tool({
+    name: "select_mode",
+    description:
+      "Select a mode and receive step-by-step guidance on how to handle the task. Call this to understand the best workflow for the current mode. " +
+      'Example: `select_mode({ mode: "Review" })` or `select_mode({ mode: "Plan", issue_number: 1234 })`.',
+    parameters: SelectModeParams,
+    execute: execute(async (params) => {
+      if (ctx.toolState.selectedMode) {
+        return {
+          error: `mode already selected: "${ctx.toolState.selectedMode}". mode selection is final and cannot be changed. complete your current workflow within this mode.`,
+        };
+      }
+
+      const modeName = params.mode;
+
+      const selectedMode = resolveMode(ctx.modes, modeName);
+
+      if (!selectedMode) {
+        const availableModes = ctx.modes.map((m) => m.name).join(", ");
+        return {
+          error: `mode "${modeName}" not found. available modes: ${availableModes}`,
+          availableModes: ctx.modes.map((m) => ({
+            name: m.name,
+            description: m.description,
+          })),
+        };
+      }
+
+      ctx.toolState.selectedMode = selectedMode.name;
+
+      if (selectedMode.name === "Plan") {
+        const issueNumber = params.issue_number ?? ctx.payload.event.issue_number;
+        if (issueNumber !== undefined) {
+          const existing = await fetchExistingPlanComment(ctx, issueNumber);
+          if (existing !== null) {
+            ctx.toolState.existingPlanCommentId = existing.commentId;
+            ctx.toolState.previousPlanBody = existing.body;
+            return {
+              ...buildOrchestratorGuidance(ctx, selectedMode, overrides.PlanEdit),
+              previousPlanBody: existing.body,
+            };
+          }
+        }
+      }
+
+      const summaryAddendum = SUMMARY_MODES.has(selectedMode.name)
+        ? buildSummaryAddendum(t, ctx)
+        : "";
+
+      const base = buildOrchestratorGuidance(ctx, selectedMode);
+      if (summaryAddendum.length > 0) {
+        return {
+          ...base,
+          orchestratorGuidance: `${base.orchestratorGuidance}\n\n${summaryAddendum}`,
+          summaryFilePath: ctx.toolState.summaryFilePath,
+        };
+      }
+      return base;
+    }),
+  });
+}

package/src/mcp/server.test.ts

@@ -0,0 +1,292 @@
+import { createServer, type Server } from "node:net";
+import { tmpdir } from "node:os";
+import { FastMCP } from "fastmcp";
+import { afterEach, beforeEach, describe, expect, it, type MockInstance, vi } from "vitest";
+import { startMcpHttpServer, type ToolContext } from "#app/mcp/server";
+import { initToolState } from "#app/toolState";
+
+type McpHandle = Awaited<ReturnType<typeof startMcpHttpServer>>;
+
+type CtxOverrides = {
+  trigger?: string;
+  shell?: "restricted" | "enabled" | "disabled";
+};
+
+function makeCtx(overrides: CtxOverrides = {}): ToolContext {
+  const ctx = {
+    agentId: "claude",
+    repo: {
+      owner: "octo",
+      name: "repo",
+      fullName: "octo/repo",
+      data: { default_branch: "main" },
+    },
+    payload: {
+      event: { trigger: overrides.trigger ?? "unknown" },
+      shell: overrides.shell ?? "restricted",
+      push: "enabled",
+      model: "anthropic/claude-opus-4",
+    },
+    octokit: {},
+    githubInstallationToken: "ghs_installation",
+    gitToken: "ghs_git",
+    apiToken: "api_jwt",
+    modes: [],
+    postCheckoutScript: null,
+    prepushScript: null,
+    prApproveEnabled: false,
+    modeInstructions: {},
+    toolState: initToolState({ progressComment: undefined }),
+    runId: undefined,
+    mcpServerUrl: "",
+    mcpServerToken: "",
+    tmpdir: tmpdir(),
+    oss: false,
+    plan: "none",
+    resolvedModel: "anthropic/claude-opus-4",
+  };
+  return ctx as unknown as ToolContext;
+}
+
+function occupyPort(): Promise<{ server: Server; port: number }> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        reject(new Error("failed to bind blocker port"));
+        return;
+      }
+      resolve({ server, port: addr.port });
+    });
+  });
+}
+
+function closeServer(server: Server): Promise<void> {
+  return new Promise((resolve) => server.close(() => resolve()));
+}
+
+let handle: McpHandle | undefined;
+let addToolSpy: MockInstance<FastMCP["addTool"]>;
+
+function registeredToolNames(): string[] {
+  return addToolSpy.mock.calls.map((call) => (call[0] as { name: string }).name);
+}
+
+beforeEach(() => {
+  addToolSpy = vi.spyOn(FastMCP.prototype, "addTool");
+});
+
+afterEach(async () => {
+  if (handle) {
+    await handle[Symbol.asyncDispose]();
+    handle = undefined;
+  }
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+});
+
+describe("startMcpHttpServer", () => {
+  it("starts on a loopback port and serves the /mcp endpoint", async () => {
+    handle = await startMcpHttpServer(makeCtx());
+    expect(handle.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/mcp$/);
+
+    // the port is actually listening — a GET reaches the http-stream transport
+    const res = await fetch(handle.url);
+    expect(res.status).toBeGreaterThanOrEqual(200);
+  });
+
+  it("requires the per-run bearer token to open a session", async () => {
+    handle = await startMcpHttpServer(makeCtx());
+    expect(handle.token).toMatch(/[0-9a-f-]{16,}/i);
+
+    const initBody = JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+        clientInfo: { name: "test", version: "0" },
+      },
+    });
+    const baseHeaders = {
+      "content-type": "application/json",
+      accept: "application/json, text/event-stream",
+    };
+
+    // no Authorization header → the transport rejects before a session opens.
+    const unauth = await fetch(handle.url, {
+      method: "POST",
+      headers: baseHeaders,
+      body: initBody,
+    });
+    expect(unauth.status).toBe(401);
+
+    // wrong token → still rejected.
+    const wrong = await fetch(handle.url, {
+      method: "POST",
+      headers: { ...baseHeaders, authorization: "Bearer not-the-token" },
+      body: initBody,
+    });
+    expect(wrong.status).toBe(401);
+
+    // correct token → not rejected with 401 (the session proceeds).
+    const authed = await fetch(handle.url, {
+      method: "POST",
+      headers: { ...baseHeaders, authorization: `Bearer ${handle.token}` },
+      body: initBody,
+    });
+    expect(authed.status).not.toBe(401);
+  });
+
+  it("registers orchestrator tools including push/PR and standalone set_output", async () => {
+    handle = await startMcpHttpServer(makeCtx({ trigger: "unknown", shell: "restricted" }));
+
+    const names = registeredToolNames();
+    expect(names).toContain("git");
+    expect(names).toContain("push_branch");
+    expect(names).toContain("create_pull_request");
+    expect(names).toContain("select_mode");
+    expect(names).toContain("report_progress");
+    expect(names).toContain("terraform_scan");
+    // standalone trigger → set_output available even without an output schema
+    expect(names).toContain("set_output");
+    // restricted shell → MCP shell + kill tools
+    expect(names).toContain("shell");
+  });
+
+  it("omits set_output and shell tools when not standalone and shell is enabled", async () => {
+    handle = await startMcpHttpServer(makeCtx({ trigger: "issue_comment", shell: "enabled" }));
+
+    const names = registeredToolNames();
+    expect(names).not.toContain("set_output");
+    expect(names).not.toContain("shell");
+    expect(names).not.toContain("kill_background");
+  });
+
+  it("registers set_output for event runs when an output schema is provided", async () => {
+    handle = await startMcpHttpServer(makeCtx({ trigger: "issue_comment", shell: "enabled" }), {
+      outputSchema: {
+        type: "object",
+        properties: { verdict: { type: "string" } },
+        required: ["verdict"],
+      },
+    });
+
+    expect(registeredToolNames()).toContain("set_output");
+  });
+});
+
+describe("port selection", () => {
+  it("honors TERRAMEND_MCP_PORT when the port is free", async () => {
+    // find a free port, then release it for the server to claim
+    const { server, port } = await occupyPort();
+    await closeServer(server);
+
+    vi.stubEnv("TERRAMEND_MCP_PORT", String(port));
+    handle = await startMcpHttpServer(makeCtx());
+    expect(handle.url).toBe(`http://127.0.0.1:${port}/mcp`);
+  });
+
+  it("falls back to scanning when TERRAMEND_MCP_PORT is occupied", async () => {
+    const { server, port } = await occupyPort();
+    try {
+      vi.stubEnv("TERRAMEND_MCP_PORT", String(port));
+      handle = await startMcpHttpServer(makeCtx());
+      expect(handle.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/mcp$/);
+      expect(handle.url).not.toContain(`:${port}/`);
+    } finally {
+      await closeServer(server);
+    }
+  });
+
+  it("rejects an invalid TERRAMEND_MCP_PORT", async () => {
+    vi.stubEnv("TERRAMEND_MCP_PORT", "not-a-port");
+    await expect(startMcpHttpServer(makeCtx())).rejects.toThrow(
+      "invalid TERRAMEND_MCP_PORT: not-a-port",
+    );
+  });
+
+  it("rejects an out-of-range TERRAMEND_MCP_PORT", async () => {
+    vi.stubEnv("TERRAMEND_MCP_PORT", "70000");
+    await expect(startMcpHttpServer(makeCtx())).rejects.toThrow(
+      "invalid TERRAMEND_MCP_PORT: 70000",
+    );
+  });
+
+  it("retries the scan when a start loses the bind race (EADDRINUSE)", async () => {
+    const startSpy = vi.spyOn(FastMCP.prototype, "start");
+    startSpy.mockRejectedValueOnce(new Error("listen EADDRINUSE: address already in use"));
+
+    handle = await startMcpHttpServer(makeCtx());
+    expect(handle.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/mcp$/);
+    expect(startSpy.mock.calls.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("fails with a diagnostic when every candidate port loses the bind race", async () => {
+    // every start attempt loses the race: isPortAvailable says free, but the
+    // transport bind fails with EADDRINUSE. exhausts the whole scan range.
+    const startSpy = vi.spyOn(FastMCP.prototype, "start");
+    startSpy.mockRejectedValue(new Error("listen EADDRINUSE: address already in use"));
+
+    await expect(startMcpHttpServer(makeCtx())).rejects.toThrow(
+      /could not find available mcp port starting at 3764/,
+    );
+  }, 30_000);
+
+  it("rethrows non-EADDRINUSE start failures immediately", async () => {
+    const startSpy = vi.spyOn(FastMCP.prototype, "start");
+    startSpy.mockRejectedValue(new Error("transport exploded"));
+
+    await expect(startMcpHttpServer(makeCtx())).rejects.toThrow("transport exploded");
+  });
+});
+
+describe("disposal", () => {
+  it("stops the server and is idempotent on repeated dispose", async () => {
+    const localHandle = await startMcpHttpServer(makeCtx());
+    const url = localHandle.url;
+
+    await localHandle[Symbol.asyncDispose]();
+    const err = await fetch(url).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(Error);
+
+    // second dispose is a no-op, not a crash
+    await expect(localHandle[Symbol.asyncDispose]()).resolves.toBeUndefined();
+  });
+
+  it("SIGTERMs then SIGKILLs tracked background process groups on dispose", async () => {
+    const ctx = makeCtx();
+    ctx.toolState.backgroundProcesses.set("bg-1", {
+      pid: 424242,
+      outputPath: "/tmp/out.log",
+      pidPath: "/tmp/out.pid",
+    });
+
+    const killSpy = vi.spyOn(process, "kill").mockImplementation(() => true);
+    const localHandle = await startMcpHttpServer(ctx);
+    await localHandle[Symbol.asyncDispose]();
+
+    expect(killSpy).toHaveBeenCalledWith(-424242, "SIGTERM");
+    expect(killSpy).toHaveBeenCalledWith(-424242, "SIGKILL");
+    expect(ctx.toolState.backgroundProcesses.size).toBe(0);
+  });
+
+  it("survives kill() throwing for already-dead processes", async () => {
+    const ctx = makeCtx();
+    ctx.toolState.backgroundProcesses.set("bg-dead", {
+      pid: 434343,
+      outputPath: "/tmp/out.log",
+      pidPath: "/tmp/out.pid",
+    });
+
+    vi.spyOn(process, "kill").mockImplementation(() => {
+      throw new Error("ESRCH");
+    });
+    const localHandle = await startMcpHttpServer(ctx);
+    await expect(localHandle[Symbol.asyncDispose]()).resolves.toBeUndefined();
+    expect(ctx.toolState.backgroundProcesses.size).toBe(0);
+  });
+});