mergestorm-mcp 0.2.26 → 0.2.28

package/dist/lib/tools/repo-settings.js

@@ -0,0 +1,78 @@
+import { CommandError, REPO_SETTINGS_KEYS, listRepoSettings, patchRepoSettings, } from "mergestorm/client";
+const ARG_BY_KEY = {
+    auto_patch_enabled: "auto_patch",
+    auto_review_enabled: "auto_review",
+    auto_land_default: "auto_land",
+    merge_queue_batch_enabled: "merge_queue_batch",
+    merge_queue_batch_size: "merge_queue_batch_size",
+    merge_queue_lands_alone_paths: "merge_queue_lands_alone_paths",
+    merge_queue_overdrive: "merge_queue_overdrive",
+};
+function parseRepo(raw) {
+    const match = typeof raw === "string" ? /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(raw.trim()) : null;
+    if (!match)
+        throw new CommandError("repo takes <owner>/<repo>.", 2, "usage");
+    return { owner: match[1], repo: match[2] };
+}
+function words(value) {
+    if (value === null)
+        return "inherit";
+    if (Array.isArray(value))
+        return value.length === 0 ? "none" : value.join(",");
+    if (typeof value === "number")
+        return String(value);
+    return value ? "on" : "off";
+}
+export function repoSettingsSummary(entry) {
+    return `${entry.owner}/${entry.repo}: ${REPO_SETTINGS_KEYS.map((key) => `${ARG_BY_KEY[key]} ${words(entry[key])}`).join(" · ")}`;
+}
+export function repoSettingsPatchFromArgs(args) {
+    const patch = {};
+    for (const key of REPO_SETTINGS_KEYS) {
+        const value = args[ARG_BY_KEY[key]];
+        if (value === undefined)
+            continue;
+        if (key === "merge_queue_batch_size") {
+            if (value !== null && (typeof value !== "number" || !Number.isInteger(value))) {
+                throw new CommandError(`${ARG_BY_KEY[key]} takes a whole number or null.`, 2, "usage");
+            }
+            patch[key] = value;
+            continue;
+        }
+        if (key === "merge_queue_lands_alone_paths") {
+            if (value !== null && !(Array.isArray(value) && value.every((entry) => typeof entry === "string"))) {
+                throw new CommandError(`${ARG_BY_KEY[key]} takes a list of path patterns or null.`, 2, "usage");
+            }
+            patch[key] = value;
+            continue;
+        }
+        if (value !== null && typeof value !== "boolean") {
+            throw new CommandError(`${ARG_BY_KEY[key]} takes true, false, or null.`, 2, "usage");
+        }
+        patch[key] = value;
+    }
+    if (Object.keys(patch).length === 0) {
+        throw new CommandError(`At least one of ${Object.values(ARG_BY_KEY).join(", ")} is required.`, 2, "usage");
+    }
+    return patch;
+}
+export async function repoSettingsGet(args, cfg) {
+    const wanted = args.repo === undefined ? null : parseRepo(args.repo);
+    const all = await listRepoSettings(cfg);
+    if (!wanted) {
+        return {
+            summary: all.length === 0 ? "No repositories are connected to this account." : all.map(repoSettingsSummary).join("\n"),
+            data: { repos: all },
+        };
+    }
+    const slug = `${wanted.owner}/${wanted.repo}`.toLowerCase();
+    const entry = all.find((candidate) => `${candidate.owner}/${candidate.repo}`.toLowerCase() === slug);
+    if (!entry)
+        throw new CommandError(`${wanted.owner}/${wanted.repo} is not connected to this account.`);
+    return { summary: repoSettingsSummary(entry), data: { ...entry } };
+}
+export async function repoSettingsSet(args, cfg) {
+    const { owner, repo } = parseRepo(args.repo);
+    const entry = await patchRepoSettings(owner, repo, repoSettingsPatchFromArgs(args), cfg);
+    return { summary: repoSettingsSummary(entry), data: { ...entry } };
+}

package/dist/lib/tools/review-dismiss.d.ts

@@ -0,0 +1,16 @@
+import { type Config, type PrFindingDismissResult } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export type ReviewDismissInput = {
+    owner: string;
+    repo: string;
+    pr_number: number;
+    head_sha: string;
+    review_id: number;
+    finding_ids?: string[];
+    scope?: "findings" | "review";
+    reason?: string;
+    evidence_url?: string;
+    preview?: boolean;
+};
+export declare function reviewDismissSummary(result: PrFindingDismissResult): string;
+export declare function reviewDismiss(input: ReviewDismissInput, cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/review-dismiss.js

@@ -0,0 +1,68 @@
+import { dismissPrFindings, dismissThreadsLine, stackWatchObligation, } from "mergestorm/client";
+import { withWatchText } from "./stack-wait.js";
+function findingText(finding) {
+    return `${finding.finding_id} (${finding.path ?? "review body"}: ${finding.title})`;
+}
+export function reviewDismissSummary(result) {
+    const pr = `${result.owner}/${result.repo}#${result.pr_number}`;
+    const kind = result.review_kind === "seam" ? "seam review" : "Vortex review";
+    const head = `${kind} ${result.review_id} at ${result.head_sha.slice(0, 7)}`;
+    const lines = [];
+    if (result.status === "preview") {
+        lines.push(`${pr} ${head}: ${result.remaining.length} open finding(s). Nothing was written.`);
+        for (const finding of result.remaining)
+            lines.push(`- ${findingText(finding)}`);
+    }
+    else {
+        lines.push(`${pr} ${head}: dismissed ${result.dismissed.length}, already dismissed ${result.already_dismissed.length}, still open ${result.remaining.length}.`);
+        for (const finding of result.remaining)
+            lines.push(`- open: ${findingText(finding)}`);
+        const threads = dismissThreadsLine(result);
+        if (threads)
+            lines.push(threads);
+    }
+    const seam = result.gate.seam;
+    if (seam) {
+        lines.push(seam.cleared
+            ? "Seam gate cleared at this head. CI, other reviews and Auto land policy are unchanged."
+            : seam.blocking
+                ? `Seam gate still blocking (seam_state=${seam.state}).`
+                : `Seam gate not blocking (seam_state=${seam.state}).`);
+    }
+    const vortex = result.gate.vortex;
+    if (vortex?.cleared) {
+        lines.push("Vortex gate cleared at this head: every Vortex Blocker (error finding) at this head is dismissed. CI and Auto land policy are unchanged.");
+    }
+    else if (vortex?.message && vortex.reason !== "review_findings_open") {
+        lines.push(`Vortex gate not cleared: ${vortex.message}`);
+    }
+    return lines.join("\n");
+}
+export async function reviewDismiss(input, cfg) {
+    const request = {
+        owner: input.owner,
+        repo: input.repo,
+        prNumber: input.pr_number,
+        headSha: input.head_sha,
+        reviewId: input.review_id,
+        ...(input.scope ? { scope: input.scope } : {}),
+        ...(input.finding_ids ? { findingIds: input.finding_ids } : {}),
+        ...(input.reason !== undefined ? { reason: input.reason } : {}),
+        ...(input.evidence_url ? { evidenceUrl: input.evidence_url } : {}),
+        ...(input.preview ? { preview: true } : {}),
+    };
+    const outcome = await dismissPrFindings(request, cfg);
+    if (!outcome.ok) {
+        return {
+            summary: `review_dismiss refused (${outcome.error}): ${outcome.message}`,
+            isError: true,
+            data: { error: { code: outcome.error, message: outcome.message, status: outcome.status } },
+        };
+    }
+    const result = outcome.result;
+    const summary = reviewDismissSummary(result);
+    if (!result.stack_id)
+        return { summary, data: { ...result } };
+    const watch = stackWatchObligation({ stackId: result.stack_id, terminal: null, unread: true, freshCursor: true });
+    return { summary: withWatchText(watch, summary), data: { ...result, watch } };
+}

package/dist/lib/tools/review-get-pr.d.ts

@@ -0,0 +1,22 @@
+import { type Config, type PrVortexReview } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare function prReviewTarget(owner: string, repo: string, prNumber: number): {
+    owner: string;
+    repo: string;
+    prNumber: number;
+};
+export declare function prReviewSummary(owner: string, repo: string, prNumber: number, envelope: {
+    status: string;
+    head_sha?: string | null;
+    finding_count?: number | null;
+    phase?: string | null;
+}): string;
+export declare function payloadFromPrReview(owner: string, repo: string, prNumber: number, envelope: PrVortexReview): ToolPayload;
+export declare function payloadFromPrRateLimit(err: unknown, owner: string, repo: string, prNumber: number): ToolPayload | null;
+/** SHA + pass selection (#2027): `pass` is one exact attempt, `afterPass` a later one on the head. */
+export type ReviewGetPrOptions = {
+    afterSha?: string;
+    pass?: number;
+    afterPass?: number;
+};
+export declare function reviewGetPr(owner: string, repo: string, prNumber: number, cfg?: Config, opts?: ReviewGetPrOptions): Promise<ToolPayload>;

package/dist/lib/tools/review-get-pr.js

@@ -0,0 +1,52 @@
+import { CommandError, getPrVortexReview, isCommandErrorCode, } from "mergestorm/client";
+export function prReviewTarget(owner, repo, prNumber) {
+    const cleanOwner = owner.trim();
+    const cleanRepo = repo.trim();
+    if (!cleanOwner || !cleanRepo || !Number.isInteger(prNumber) || prNumber <= 0) {
+        throw new CommandError("owner, repo, and a positive pr_number are required", 2, "usage");
+    }
+    return { owner: cleanOwner, repo: cleanRepo, prNumber };
+}
+export function prReviewSummary(owner, repo, prNumber, envelope) {
+    const bits = [`${owner}/${repo}#${prNumber}`, envelope.status];
+    const sha = envelope.head_sha?.trim();
+    if (sha)
+        bits.push(`sha ${sha.slice(0, 7)}`);
+    if (typeof envelope.finding_count === "number") {
+        bits.push(`${envelope.finding_count} finding${envelope.finding_count === 1 ? "" : "s"}`);
+    }
+    if (envelope.phase)
+        bits.push(String(envelope.phase));
+    return bits.join(" · ");
+}
+export function payloadFromPrReview(owner, repo, prNumber, envelope) {
+    return {
+        summary: prReviewSummary(owner, repo, prNumber, envelope),
+        data: { ...envelope },
+    };
+}
+export function payloadFromPrRateLimit(err, owner, repo, prNumber) {
+    if (!isCommandErrorCode(err, "rate_limited"))
+        return null;
+    return {
+        summary: `${owner}/${repo}#${prNumber} · rate_limited`,
+        data: {
+            status: "rate_limited",
+            error: err.message,
+            retry_after_seconds: err.retryAfterSeconds,
+        },
+    };
+}
+export async function reviewGetPr(owner, repo, prNumber, cfg, opts = {}) {
+    const target = prReviewTarget(owner, repo, prNumber);
+    try {
+        const envelope = await getPrVortexReview(target.owner, target.repo, target.prNumber, cfg, { afterSha: opts.afterSha, pass: opts.pass, afterPass: opts.afterPass });
+        return payloadFromPrReview(target.owner, target.repo, target.prNumber, envelope);
+    }
+    catch (err) {
+        const rateLimited = payloadFromPrRateLimit(err, target.owner, target.repo, target.prNumber);
+        if (rateLimited)
+            return rateLimited;
+        throw err;
+    }
+}

package/dist/lib/tools/review-get.d.ts

@@ -0,0 +1,3 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare function reviewGet(jobId: string, cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/review-get.js

@@ -0,0 +1,27 @@
+import { CommandError, getReview, toReviewJobEnvelope, } from "mergestorm/client";
+import { payloadFromRateLimit } from "./envelope.js";
+export async function reviewGet(jobId, cfg) {
+    let row;
+    try {
+        row = await getReview(jobId, cfg);
+    }
+    catch (err) {
+        const rateLimited = payloadFromRateLimit(err, jobId);
+        if (rateLimited)
+            return rateLimited;
+        throw err;
+    }
+    if (!row ||
+        typeof row !== "object" ||
+        typeof row.status !== "string") {
+        throw new CommandError(`Unexpected response for review ${jobId}.`);
+    }
+    const envelope = toReviewJobEnvelope(row, { jobId });
+    const bits = [envelope.status];
+    if (envelope.verdict)
+        bits.push(envelope.verdict);
+    return {
+        summary: `${envelope.job_id ?? jobId} · ${bits.join(" · ")}`,
+        data: envelope,
+    };
+}

package/dist/lib/tools/review-list.d.ts

@@ -0,0 +1,3 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare function reviewList(limit?: number, cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/review-list.js

@@ -0,0 +1,10 @@
+import { listJobs, toReviewJobEnvelope } from "mergestorm/client";
+export async function reviewList(limit = 10, cfg) {
+    const items = await listJobs(limit, cfg);
+    const envelopes = items.map((row) => toReviewJobEnvelope(row));
+    const n = envelopes.length;
+    return {
+        summary: n === 0 ? "No review jobs" : `${n} review job${n === 1 ? "" : "s"}`,
+        data: { items: envelopes },
+    };
+}

package/dist/lib/tools/review-start.d.ts

@@ -0,0 +1,11 @@
+import type { Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export type PullRequestInput = {
+    owner: string;
+    repo: string;
+    pr_number: number;
+};
+export declare function reviewStartPr(input: PullRequestInput & {
+    head_sha?: string;
+}, cfg?: Config, chatId?: string | null): Promise<ToolPayload>;
+export declare function reviewStopPr(input: PullRequestInput, cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/review-start.js

@@ -0,0 +1,22 @@
+import { agentRequest } from "./agent-request.js";
+import { chatTaskNote, chatTaskOf } from "./chat-task.js";
+export async function reviewStartPr(input, cfg, chatId) {
+    const payload = await agentRequest("/api/v1/agents/vortex/review", {
+        method: "POST",
+        json: {
+            owner: input.owner,
+            repo: input.repo,
+            pr_number: input.pr_number,
+            ...(input.head_sha ? { head_sha: input.head_sha } : {}),
+            ...(chatId ? { chat_id: chatId } : {}),
+        },
+    }, cfg);
+    const task = chatTaskOf(payload.data.background_task);
+    return task ? { ...payload, summary: `${payload.summary} ${chatTaskNote(task)}` } : payload;
+}
+export async function reviewStopPr(input, cfg) {
+    return agentRequest("/api/v1/agents/vortex/stop", {
+        method: "POST",
+        json: { owner: input.owner, repo: input.repo, pr_number: input.pr_number },
+    }, cfg);
+}

package/dist/lib/tools/review-submit.d.ts

@@ -0,0 +1,36 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+/** Hard maximum for an explicitly requested MCP poll slice. */
+export declare const MCP_WAIT_CEILING_S = 300;
+/**
+ * Default bound for local and PR review waits. Reviews can take minutes or hours;
+ * Cursor kills a single MCP call around a minute, so this is one poll
+ * slice. The skill loops until the review finishes.
+ */
+export declare const MCP_PR_WAIT_DEFAULT_S = 45;
+export declare function assertPinnableSpecialists(specialists: string[] | undefined): void;
+/**
+ * Host-configured root that agent-chosen `context_files` may not escape.
+ * The `cwd` tool argument is agent-controlled, so it cannot serve as the
+ * sandbox root; default to the MCP server's own working directory.
+ */
+export declare function mcpSandboxRoot(): string;
+export type ReviewSubmitInput = {
+    cwd?: string;
+    base?: string;
+    head?: string;
+    diff?: string;
+    router?: string;
+    specialists?: string[];
+    context?: string;
+    context_files?: string[];
+    thread?: string;
+    idempotency_key?: string;
+    wait?: boolean;
+    timeout_s?: number;
+};
+export type ReviewSubmitOptions = {
+    pollIntervalMs?: number;
+};
+export declare function waitTimeoutMs(timeout_s?: number, defaultSeconds?: number): number;
+export declare function reviewSubmit(input: ReviewSubmitInput, cfg?: Config, opts?: ReviewSubmitOptions): Promise<ToolPayload>;

package/dist/lib/tools/review-submit.js

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+import { CommandError, REVIEW_THREAD_SLUG_RE, ReviewPollTimeoutError, collectReviewInput, discoverTrunk, formatReviewSubmitError, loadConfig, loadReviewContext, pollReview, rateLimitedMessage, submitReview, } from "mergestorm/client";
+import { payloadFromRateLimit, payloadFromRow } from "./envelope.js";
+/** Hard maximum for an explicitly requested MCP poll slice. */
+export const MCP_WAIT_CEILING_S = 300;
+/**
+ * Default bound for local and PR review waits. Reviews can take minutes or hours;
+ * Cursor kills a single MCP call around a minute, so this is one poll
+ * slice. The skill loops until the review finishes.
+ */
+export const MCP_PR_WAIT_DEFAULT_S = 45;
+/** Pinnable L0 lanes. `governance` and `seam` are L1 and cannot be requested. */
+const PINNABLE_SPECIALISTS = [
+    "security",
+    "performance",
+    "architecture",
+    "tests",
+    "data",
+    "api",
+    "frontend",
+];
+export function assertPinnableSpecialists(specialists) {
+    if (!specialists?.length)
+        return;
+    const unknown = specialists.filter((id) => !PINNABLE_SPECIALISTS.includes(id));
+    if (unknown.length === 0)
+        return;
+    throw new CommandError(`Unknown specialist: ${unknown.join(", ")}. Valid lanes: ${PINNABLE_SPECIALISTS.join(", ")}. governance and seam cannot be requested.`, 2, "usage");
+}
+/**
+ * Host-configured root that agent-chosen `context_files` may not escape.
+ * The `cwd` tool argument is agent-controlled, so it cannot serve as the
+ * sandbox root; default to the MCP server's own working directory.
+ */
+export function mcpSandboxRoot() {
+    return process.env.MERGESTORM_SANDBOX_ROOT?.trim() || process.cwd();
+}
+export function waitTimeoutMs(timeout_s, defaultSeconds = MCP_PR_WAIT_DEFAULT_S) {
+    const seconds = timeout_s ?? defaultSeconds;
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        throw new CommandError("timeout_s must be a positive number of seconds", 2, "usage");
+    }
+    return Math.max(1, Math.round(Math.min(seconds, MCP_WAIT_CEILING_S) * 1_000));
+}
+async function resolveInput(input) {
+    const cwd = input.cwd ?? process.cwd();
+    const head = input.head?.trim() || "HEAD";
+    if (input.diff?.trim()) {
+        const branch = "local";
+        const thread = input.thread?.trim() ||
+            `local/diff-${createHash("sha256").update(input.diff).digest("hex").slice(0, 12)}`;
+        return {
+            thread,
+            branch,
+            baseLabel: input.base?.trim() ||
+                (() => {
+                    try {
+                        return discoverTrunk(cwd);
+                    }
+                    catch {
+                        return "main";
+                    }
+                })(),
+            headLabel: head,
+            diff: input.diff,
+            files: [],
+        };
+    }
+    const sandboxRoot = mcpSandboxRoot();
+    try {
+        const [sandboxReal, cwdReal] = await Promise.all([
+            realpath(resolve(sandboxRoot)),
+            realpath(resolve(cwd)),
+        ]);
+        const relToSandbox = relative(sandboxReal, cwdReal);
+        if (relToSandbox === ".." || relToSandbox.startsWith(`..${sep}`)) {
+            throw new CommandError("cwd must be inside the configured sandbox root", 2, "usage");
+        }
+    }
+    catch (err) {
+        if (err instanceof CommandError)
+            throw err;
+        throw new CommandError("cwd must be inside the configured sandbox root", 2, "usage");
+    }
+    const base = input.base?.trim() || discoverTrunk(cwd);
+    return collectReviewInput(base, head, cwd, sandboxRoot);
+}
+export async function reviewSubmit(input, cfg, opts = {}) {
+    const resolved = cfg ?? (await loadConfig());
+    const wait = input.wait === true;
+    const timeoutMs = waitTimeoutMs(input.timeout_s);
+    assertPinnableSpecialists(input.specialists);
+    if (input.thread && !REVIEW_THREAD_SLUG_RE.test(input.thread)) {
+        throw new CommandError("thread must be 1–120 chars [A-Za-z0-9._/-]", 2, "usage");
+    }
+    if (input.context === "-") {
+        throw new CommandError('context "-" (stdin) is not available over MCP; pass the text directly', 2, "usage");
+    }
+    const collected = await resolveInput(input);
+    if (!collected) {
+        return payloadFromRow(null, { status: "no_changes" });
+    }
+    if (input.thread)
+        collected.thread = input.thread;
+    const extras = await loadReviewContext({
+        context: input.context,
+        contextFiles: input.context_files ?? [],
+        cwd: input.cwd ?? process.cwd(),
+        sandboxCwd: mcpSandboxRoot(),
+    });
+    const submitted = await submitReview(resolved, collected, {
+        routerMode: input.router,
+        specialists: input.specialists,
+        context: extras.context,
+        contextFiles: extras.contextFiles,
+        idempotencyKey: input.idempotency_key,
+    });
+    const jobId = submitted.row.job_id ?? submitted.row.id ?? null;
+    if (submitted.status === 402) {
+        return payloadFromRow(submitted.row, {
+            jobId,
+            status: "quota_exceeded",
+            error: "Review limit reached for this period.",
+        });
+    }
+    if (submitted.status === 429) {
+        return payloadFromRow(submitted.row, {
+            jobId,
+            status: "rate_limited",
+            error: rateLimitedMessage(submitted.retryAfterSeconds),
+            retryAfterSeconds: submitted.retryAfterSeconds,
+        });
+    }
+    if (submitted.status !== 202 && submitted.status !== 200) {
+        return {
+            ...payloadFromRow({ ...submitted.row, status: "failed" }, {
+                jobId,
+                error: formatReviewSubmitError(submitted.status, submitted.row),
+            }),
+            isError: true,
+        };
+    }
+    if (!jobId) {
+        throw new CommandError("Review API returned no job_id");
+    }
+    if (!wait) {
+        return payloadFromRow(submitted.row, { jobId, status: submitted.row.status ?? "queued" });
+    }
+    let row;
+    try {
+        row = await pollReview(resolved, jobId, {
+            timeoutMs,
+            intervalMs: opts.pollIntervalMs,
+        });
+    }
+    catch (err) {
+        if (err instanceof ReviewPollTimeoutError) {
+            return payloadFromRow(err.lastRow, {
+                jobId,
+                status: err.lastRow.status ?? "in_progress",
+                error: "Timed out waiting for review.",
+            });
+        }
+        const rateLimited = payloadFromRateLimit(err, jobId);
+        if (rateLimited)
+            return rateLimited;
+        throw err;
+    }
+    return payloadFromRow(row, { jobId });
+}

package/dist/lib/tools/review-wait-pr.d.ts

@@ -0,0 +1,11 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export type ReviewWaitPrOptions = {
+    pollIntervalMs?: number;
+    /** Exact pass on the head (#2027). */
+    pass?: number;
+    /** Only a pass later than this one on the head; fixed for the whole wait (#2027). */
+    afterPass?: number;
+    chatId?: string;
+};
+export declare function reviewWaitPr(owner: string, repo: string, prNumber: number, afterSha?: string, timeout_s?: number, cfg?: Config, opts?: ReviewWaitPrOptions): Promise<ToolPayload>;

package/dist/lib/tools/review-wait-pr.js

@@ -0,0 +1,66 @@
+import { PrReviewPollTimeoutError, loadConfig, noPrReviewYetMessage, pollPrVortexReview, } from "mergestorm/client";
+import { payloadFromPrRateLimit, payloadFromPrReview, prReviewSummary, prReviewTarget, reviewGetPr, } from "./review-get-pr.js";
+import { MCP_PR_WAIT_DEFAULT_S, waitTimeoutMs } from "./review-submit.js";
+import { chatTaskNote, trackInChat } from "./chat-task.js";
+export async function reviewWaitPr(owner, repo, prNumber, afterSha, timeout_s, cfg, opts = {}) {
+    const target = prReviewTarget(owner, repo, prNumber);
+    const resolved = cfg ?? (await loadConfig());
+    if (timeout_s === 0) {
+        return reviewGetPr(target.owner, target.repo, target.prNumber, resolved, {
+            afterSha,
+            pass: opts.pass,
+            afterPass: opts.afterPass,
+        });
+    }
+    try {
+        const envelope = await pollPrVortexReview(resolved, target.owner, target.repo, target.prNumber, {
+            timeoutMs: waitTimeoutMs(timeout_s, MCP_PR_WAIT_DEFAULT_S),
+            afterSha,
+            pass: opts.pass,
+            afterPass: opts.afterPass,
+            intervalMs: opts.pollIntervalMs,
+        });
+        return payloadFromPrReview(target.owner, target.repo, target.prNumber, envelope);
+    }
+    catch (err) {
+        if (err instanceof PrReviewPollTimeoutError) {
+            const status = err.reviewSeen ? "in_progress" : "none";
+            const expectedSha = afterSha?.trim().toLowerCase() ?? "";
+            const observedSha = err.lastEnvelope?.head_sha?.trim().toLowerCase() ?? "";
+            const headShaMatches = Boolean(observedSha &&
+                expectedSha.length >= 7 &&
+                (observedSha.startsWith(expectedSha) || expectedSha.startsWith(observedSha)));
+            const findingCount = headShaMatches
+                ? err.lastEnvelope?.finding_count ?? null
+                : null;
+            const summary = prReviewSummary(target.owner, target.repo, target.prNumber, {
+                status,
+                head_sha: err.lastEnvelope?.head_sha ?? null,
+                finding_count: findingCount,
+                phase: err.lastEnvelope?.phase ?? null,
+            });
+            const task = opts.chatId
+                ? await trackInChat(resolved, opts.chatId, { kind: "review", owner: target.owner, repo: target.repo, prNumber: target.prNumber })
+                : null;
+            const shown = err.reviewSeen
+                ? summary
+                : `${summary} · ${noPrReviewYetMessage(target.owner, target.repo, target.prNumber, { afterSha, pass: opts.pass, afterPass: opts.afterPass })}`;
+            return {
+                summary: task ? `${shown} · ${chatTaskNote(task)}` : shown,
+                data: {
+                    status,
+                    head_sha: err.lastEnvelope?.head_sha ?? null,
+                    pass: headShaMatches ? err.lastEnvelope?.pass ?? null : null,
+                    finding_count: findingCount,
+                    phase: err.lastEnvelope?.phase ?? null,
+                    error: err.message,
+                    ...(task ? { background_task: task } : {}),
+                },
+            };
+        }
+        const rateLimited = payloadFromPrRateLimit(err, target.owner, target.repo, target.prNumber);
+        if (rateLimited)
+            return rateLimited;
+        throw err;
+    }
+}

package/dist/lib/tools/review-wait.d.ts

@@ -0,0 +1,6 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export type ReviewWaitOptions = {
+    pollIntervalMs?: number;
+};
+export declare function reviewWait(jobId: string, timeout_s?: number, cfg?: Config, opts?: ReviewWaitOptions): Promise<ToolPayload>;

package/dist/lib/tools/review-wait.js

@@ -0,0 +1,33 @@
+import { CommandError, ReviewPollTimeoutError, loadConfig, pollReview, } from "mergestorm/client";
+import { payloadFromRateLimit, payloadFromRow } from "./envelope.js";
+import { reviewGet } from "./review-get.js";
+import { waitTimeoutMs } from "./review-submit.js";
+export async function reviewWait(jobId, timeout_s, cfg, opts = {}) {
+    const resolved = cfg ?? (await loadConfig());
+    const id = jobId.trim();
+    if (!id) {
+        throw new CommandError("job_id is required", 2, "usage");
+    }
+    if (timeout_s === 0)
+        return reviewGet(id, resolved);
+    try {
+        const row = await pollReview(resolved, id, {
+            timeoutMs: waitTimeoutMs(timeout_s),
+            intervalMs: opts.pollIntervalMs,
+        });
+        return payloadFromRow(row, { jobId: id });
+    }
+    catch (err) {
+        if (err instanceof ReviewPollTimeoutError) {
+            return payloadFromRow(err.lastRow, {
+                jobId: id,
+                status: err.lastRow.status ?? "in_progress",
+                error: "Timed out waiting for review.",
+            });
+        }
+        const rateLimited = payloadFromRateLimit(err, id);
+        if (rateLimited)
+            return rateLimited;
+        throw err;
+    }
+}

package/dist/lib/tools/settings-get.d.ts

@@ -0,0 +1,8 @@
+import { type Config, type SettingsResponse } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+/**
+ * One line an agent can act on without opening the data: is Cyclone allowed
+ * to patch, and is it even connected.
+ */
+export declare function settingsSummary(settings: SettingsResponse): string;
+export declare function settingsGet(cfg?: Config): Promise<ToolPayload>;