mergestorm 0.3.13 → 0.3.15

package/dist/commands/pr.js

@@ -0,0 +1,127 @@
+import { getPrVortexReview } from "../api.js";
+import { loadConfig } from "../config.js";
+import { CommandError, REVIEW_EXIT } from "../errors.js";
+import { ansi } from "../ui/ansi.js";
+import { renderFindings } from "../ui/findings.js";
+import { PrReviewPollTimeoutError, REVIEW_POLL_DEFAULT_TIMEOUT_MS, pollPrVortexReview, } from "./review-client.js";
+import { parseAdoptTarget } from "./stack.js";
+const PR_USAGE = "usage: mergestorm pr <owner/repo>#<n> [--json] [--wait] [--after-sha <sha>] [--timeout <s>]";
+function usageError(message = PR_USAGE) {
+    return new CommandError(message, REVIEW_EXIT.usage, "usage");
+}
+export function parsePrArgs(args, defaults = { format: "json" }) {
+    const target = [];
+    let format = defaults.format;
+    let wait = false;
+    let afterSha;
+    let timeoutMs = REVIEW_POLL_DEFAULT_TIMEOUT_MS;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--json") {
+            format = "json";
+            continue;
+        }
+        if (arg === "--pretty") {
+            format = "pretty";
+            continue;
+        }
+        if (arg === "--wait") {
+            wait = true;
+            continue;
+        }
+        if (arg === "--after-sha" || arg.startsWith("--after-sha=")) {
+            const value = arg === "--after-sha" ? args[++i] : arg.slice("--after-sha=".length);
+            if (!value?.trim())
+                throw usageError("--after-sha requires a non-empty SHA");
+            afterSha = value.trim();
+            if (afterSha.length < 7) {
+                throw usageError("--after-sha must be at least 7 characters");
+            }
+            if (!/^[0-9a-f]+$/i.test(afterSha)) {
+                throw usageError("--after-sha must contain only hexadecimal characters");
+            }
+            continue;
+        }
+        if (arg === "--timeout" || arg.startsWith("--timeout=")) {
+            const value = arg === "--timeout" ? args[++i] : arg.slice("--timeout=".length);
+            const seconds = Number(value);
+            if (!value || !Number.isFinite(seconds) || seconds <= 0) {
+                throw usageError("--timeout must be a positive number of seconds");
+            }
+            timeoutMs = Math.round(seconds * 1_000);
+            wait = true;
+            continue;
+        }
+        if (arg.startsWith("-"))
+            throw usageError(`unknown flag: ${arg}`);
+        target.push(arg);
+    }
+    if (afterSha && !wait)
+        throw usageError("--after-sha requires --wait");
+    if (target.length < 1 || target.length > 2)
+        throw usageError();
+    let parsed;
+    try {
+        parsed = parseAdoptTarget(target);
+    }
+    catch {
+        throw usageError();
+    }
+    return { ...parsed, format, wait, afterSha, timeoutMs };
+}
+function printPretty(envelope) {
+    console.log(`Status:        ${envelope.status}`);
+    if (envelope.verdict)
+        console.log(`Verdict:       ${ansi.bold(envelope.verdict)}`);
+    if (envelope.head_sha)
+        console.log(`Head:          ${envelope.head_sha}`);
+    console.log(`Finding count: ${envelope.finding_count}`);
+    if (envelope.skip_reason)
+        console.log(`Skip reason:   ${envelope.skip_reason}`);
+    if (envelope.summary)
+        console.log(envelope.summary);
+    renderFindings(envelope.findings, {
+        emptyMessage: envelope.status === "completed",
+    });
+}
+export async function cmdPr(args, opts = {}) {
+    const parsed = parsePrArgs(args, {
+        format: opts.defaultFormat ?? "json",
+    });
+    const cfg = await loadConfig();
+    let envelope;
+    if (parsed.wait) {
+        try {
+            envelope = await pollPrVortexReview(cfg, parsed.owner, parsed.repo, parsed.prNumber, {
+                timeoutMs: parsed.timeoutMs,
+                intervalMs: opts.pollIntervalMs,
+                afterSha: parsed.afterSha,
+                signal: opts.signal,
+                ...opts.poll,
+                onTick(kind) {
+                    if (parsed.format === "json")
+                        console.error(kind === "retry" ? "?" : ".");
+                    else
+                        process.stdout.write(kind === "retry" ? "?" : ".");
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof PrReviewPollTimeoutError) {
+                throw new CommandError(err.message, REVIEW_EXIT.timeout, "review_timeout");
+            }
+            throw err;
+        }
+        if (parsed.format === "pretty")
+            console.log("");
+    }
+    else {
+        envelope = await getPrVortexReview(parsed.owner, parsed.repo, parsed.prNumber, cfg, { signal: opts.signal });
+    }
+    if (parsed.format === "json") {
+        console.log(JSON.stringify(envelope, null, opts.mode === "shell" ? 2 : undefined));
+    }
+    else {
+        printPretty(envelope);
+    }
+}

package/dist/commands/queue.d.ts

@@ -0,0 +1,12 @@
+import { type MergeQueueEntryDto } from "../api.js";
+import { runLineTabsBrowser } from "../ui/line-tabs.js";
+/** Injectable seams for unit tests. Production callers omit deps. */
+export type QueueCmdDeps = {
+    canBrowse?: () => boolean;
+    runLineTabsBrowser?: typeof runLineTabsBrowser;
+};
+export declare const QUEUE_USAGE = "usage:\n  mergestorm queue [list] [--json]\n  mergestorm queue add <stack-id> [--json]\n  mergestorm queue rm <entry-id|stack-id> [--json]\n\n  queue lists your live merge-queue entries. rm prefers an entry id; a live\n  stack id is resolved to its queue entry before cancellation.";
+/** Entry ids win; otherwise a live stack id resolves to its entry id. */
+export declare function resolveQueueEntryId(idOrStackId: string, entries: readonly MergeQueueEntryDto[]): string;
+export declare function buildQueueListLines(entries: readonly MergeQueueEntryDto[], fullStackId?: boolean): string[];
+export declare function cmdQueue(args: string[], deps?: QueueCmdDeps): Promise<void>;

package/dist/commands/queue.js

@@ -0,0 +1,160 @@
+import { cancelMergeQueueEntry, enqueueStack, listMergeQueueEntries, } from "../api.js";
+import { loadConfig } from "../config.js";
+import { CommandError } from "../errors.js";
+import { ansi } from "../ui/ansi.js";
+import { runLineTabsBrowser } from "../ui/line-tabs.js";
+import { present } from "../ui/present.js";
+import { visibleWidth } from "../ui/width.js";
+import { canBrowse } from "./browse.js";
+const QUEUE_STATE_GLYPHS = {
+    queued: "○",
+    running: "●",
+    waiting: "◐",
+    bounced: "×",
+    landed: "✓",
+    cancelled: "·",
+};
+function queueStateGlyph(state) {
+    return QUEUE_STATE_GLYPHS[state] ?? "·";
+}
+function colorQueueGlyph(state, glyph) {
+    if (state === "running")
+        return ansi.brightGreen(glyph);
+    if (state === "waiting")
+        return ansi.yellow(glyph);
+    if (state === "bounced")
+        return ansi.red(glyph);
+    return ansi.dim(glyph);
+}
+export const QUEUE_USAGE = `usage:
+  mergestorm queue [list] [--json]
+  mergestorm queue add <stack-id> [--json]
+  mergestorm queue rm <entry-id|stack-id> [--json]
+
+  queue lists your live merge-queue entries. rm prefers an entry id; a live
+  stack id is resolved to its queue entry before cancellation.`;
+function positionalArgs(args) {
+    const unknown = args.filter((arg) => arg.startsWith("-") &&
+        arg !== "--json" &&
+        arg !== "-h" &&
+        arg !== "--help");
+    if (unknown.length > 0) {
+        throw new CommandError(`unknown queue option: ${unknown[0]}`, 2, "usage");
+    }
+    return args.filter((arg) => arg !== "--json");
+}
+function requireIdentifier(value, usage) {
+    const id = value?.trim();
+    if (!id)
+        throw new CommandError(usage, 2, "usage");
+    return id;
+}
+/** Entry ids win; otherwise a live stack id resolves to its entry id. */
+export function resolveQueueEntryId(idOrStackId, entries) {
+    const entry = entries.find((candidate) => candidate.id === idOrStackId);
+    if (entry)
+        return entry.id;
+    const stackEntry = entries.find((candidate) => candidate.stackId === idOrStackId);
+    return stackEntry?.id ?? idOrStackId;
+}
+export function buildQueueListLines(entries, fullStackId = false) {
+    if (entries.length === 0) {
+        return [
+            `  ${ansi.bold("Nothing queued")}`,
+            "",
+            `  ${ansi.brightGreen("queue add <stack-id>")}  send a stack for verified landing`,
+        ];
+    }
+    return entries.map((entry) => {
+        const reason = entry.waitReason ?? entry.bounceReason;
+        const glyph = colorQueueGlyph(entry.state, queueStateGlyph(entry.state));
+        const id = fullStackId ? entry.stackId : entry.stackId.slice(0, 8);
+        const core = `  ${String(entry.position).padStart(2)}  ` +
+            `${glyph} ${entry.state.padEnd(8)}  ${entry.owner}/${entry.repo}  ${id}` +
+            (reason ? `  ${reason}` : "");
+        const who = entry.enqueuedBy === "human" || entry.enqueuedBy === "agent"
+            ? `  by ${entry.enqueuedBy}`
+            : "";
+        const withWho = `${core}${who}`;
+        return visibleWidth(withWho) <= 75 ? withWho : core;
+    });
+}
+async function listQueue(asJson, deps = {}) {
+    const cfg = await loadConfig();
+    const entries = await listMergeQueueEntries(cfg);
+    if (asJson) {
+        console.log(JSON.stringify({ entries }, null, 2));
+        return;
+    }
+    const browse = deps.canBrowse ?? canBrowse;
+    const browseable = browse();
+    const lines = buildQueueListLines(entries, !browseable);
+    if (browseable) {
+        const runBrowser = deps.runLineTabsBrowser ?? runLineTabsBrowser;
+        await runBrowser({
+            tabs: [{ id: "queue", label: "Queue", lines }],
+        });
+        return;
+    }
+    await present("Merge queue", lines);
+}
+async function addQueue(args, asJson) {
+    const id = requireIdentifier(args[0], "usage: mergestorm queue add <stack-id> [--json]");
+    if (args.length > 1) {
+        throw new CommandError("usage: mergestorm queue add <stack-id> [--json]", 2, "usage");
+    }
+    const cfg = await loadConfig();
+    const body = await enqueueStack(id, cfg);
+    if (asJson) {
+        console.log(JSON.stringify(body, null, 2));
+        return;
+    }
+    const entry = body?.entry;
+    const duplicate = body?.duplicate === true;
+    await present("Merge queue", [
+        ansi.brightGreen(`  ${duplicate ? "Already queued" : "Queued"} ${id}` +
+            (entry?.position ? ` at position ${entry.position}` : "")),
+    ]);
+}
+async function removeQueue(args, asJson) {
+    const requested = requireIdentifier(args[0], "usage: mergestorm queue rm <entry-id|stack-id> [--json]");
+    if (args.length > 1) {
+        throw new CommandError("usage: mergestorm queue rm <entry-id|stack-id> [--json]", 2, "usage");
+    }
+    const cfg = await loadConfig();
+    const entries = await listMergeQueueEntries(cfg);
+    const entryId = resolveQueueEntryId(requested, entries);
+    const body = await cancelMergeQueueEntry(entryId, cfg);
+    if (asJson) {
+        console.log(JSON.stringify(body, null, 2));
+        return;
+    }
+    await present("Merge queue", [
+        ansi.brightGreen(`  Removed ${entryId} from the merge queue`),
+    ]);
+}
+export async function cmdQueue(args, deps = {}) {
+    const asJson = args.includes("--json");
+    const positional = positionalArgs(args);
+    const sub = positional[0]?.toLowerCase();
+    if (sub === "-h" || sub === "--help" || sub === "help") {
+        console.log(QUEUE_USAGE);
+        return;
+    }
+    if (!sub || sub === "list" || sub === "ls") {
+        if (positional.length > (sub ? 1 : 0)) {
+            throw new CommandError(QUEUE_USAGE, 2, "usage");
+        }
+        await listQueue(asJson, deps);
+        return;
+    }
+    if (sub === "add") {
+        await addQueue(positional.slice(1), asJson);
+        return;
+    }
+    if (sub === "rm" || sub === "remove") {
+        await removeQueue(positional.slice(1), asJson);
+        return;
+    }
+    throw new CommandError(`${QUEUE_USAGE}\nunknown queue subcommand: ${sub}`);
+}

package/dist/commands/registry.js

@@ -1,11 +1,16 @@
 import { DEFAULT_API } from "../config.js";
 import { CommandError } from "../errors.js";
 import { cmdBranches, cmdChain } from "./branches.js";
+import { canBrowse, openTabsBrowser } from "./browse.js";
 import { cmdCredits } from "./credits.js";
 import { cmdJobs, cmdThread } from "./jobs.js";
 import { cmdLogin } from "./login.js";
 import { cmdLogout } from "./logout.js";
+import { cmdQueue } from "./queue.js";
+import { cmdPr } from "./pr.js";
 import { cmdReview } from "./review.js";
+import { cmdSettings } from "./settings.js";
+import { cmdSkill } from "./skill.js";
 import { cmdStack } from "./stack.js";
 import { cmdStatus } from "./status.js";
 import { cmdWhoami } from "./whoami.js";
@@ -56,20 +61,42 @@ export const COMMAND_REGISTRY = [
             await cmdReview(args);
         },
     },
+    {
+        name: "pr",
+        summary: "Latest Vortex review for a GitHub PR",
+        usage: [
+            "mergestorm pr <owner/repo>#<n>  Fetch the latest Vortex PR review",
+            "  [--json] [--wait] [--after-sha <sha>] [--timeout <s>]",
+            "  Also accepts: mergestorm pr <owner/repo> <n>",
+        ],
+        async run(args, ctx) {
+            await cmdPr(args, {
+                defaultFormat: ctx.mode === "shell" ? "pretty" : "json",
+                signal: ctx.signal,
+                mode: ctx.mode,
+            });
+        },
+    },
     {
         name: "status",
-        summary: "Show a review job",
+        summary: "Job panel (id) or Status / Usage / Jobs tabs",
         usage: [
             "mergestorm status <job_id>      Fetch a review job (same envelope as review --json)",
             "  [--json] [--wait] [--timeout seconds]",
             "  HTTP 429 exits 7 (rate_limited) with retry_after_seconds",
+            "  With no job id on a TTY: tabbed Status / Usage / Jobs / Config browser",
         ],
         async run(args, ctx) {
+            if (args.length === 0 && canBrowse()) {
+                await openTabsBrowser("status");
+                return;
+            }
             if (ctx.mode === "shell") {
                 await cmdStatus(args, {
                     defaultFormat: "pretty",
                     signal: ctx.signal,
                     interactive: true,
+                    mode: "shell",
                 });
                 return;
             }
@@ -79,8 +106,11 @@ export const COMMAND_REGISTRY = [
     {
         name: "credits",
         aliases: ["usage"],
-        summary: "Usage panel: credit bar and last five jobs",
-        usage: ["mergestorm credits [--json]     Usage panel (bar + last 5 jobs)"],
+        summary: "Usage: tabbed browser (TTY) or static panel",
+        usage: [
+            "mergestorm credits [--json]     Usage panel (bar + last 5 jobs)",
+            "  On a TTY: tabbed Status / Usage / Jobs / Config browser (Usage selected)",
+        ],
         async run(args) {
             await cmdCredits(args);
         },
@@ -89,8 +119,14 @@ export const COMMAND_REGISTRY = [
         name: "jobs",
         summary: "Recent review jobs (default 10)",
         usage: ["mergestorm jobs [n] [--json]    Recent review jobs"],
-        async run(args) {
-            await cmdJobs(args);
+        async run(args, ctx) {
+            if (args.every((a) => a !== "--json") &&
+                !args.some((a) => /^\d+$/.test(a)) &&
+                canBrowse()) {
+                await openTabsBrowser("jobs");
+                return;
+            }
+            await cmdJobs(args, { mode: ctx.mode });
         },
     },
     {
@@ -98,26 +134,51 @@ export const COMMAND_REGISTRY = [
         aliases: ["chains"],
         summary: "Pick a recently reviewed branch",
         usage: ["mergestorm branches [n]         Recently reviewed branches (pick on TTY)"],
-        async run(args) {
-            await cmdBranches(args);
+        async run(args, ctx) {
+            await cmdBranches(args, { mode: ctx.mode });
         },
     },
     {
         name: "chain",
-        summary: "Show a branch review-chain timeline",
+        summary: "Branch review-chain timeline (holds until q)",
         usage: [
             "mergestorm chain [slug]         Branch review-chain timeline (default: current)",
         ],
-        async run(args) {
-            await cmdChain(args);
+        async run(args, ctx) {
+            await cmdChain(args, { mode: ctx.mode });
         },
     },
     {
         name: "whoami",
-        summary: "Key + plan + API base",
+        summary: "Key + plan (Status tab on a TTY)",
         usage: ["mergestorm whoami [--json]      Key + plan + API base"],
+        async run(args, ctx) {
+            await cmdWhoami(args, { mode: ctx.mode });
+        },
+    },
+    {
+        name: "settings",
+        summary: "Automation toggles (Config tab on a TTY)",
+        usage: [
+            "mergestorm settings [--json]    Read the automation toggles (Config tab on a TTY)",
+            "  [--auto-review on|off] [--auto-patch on|off] [--vortex-thinking on|off]",
+            "  [--repo-overview on|off] [--review-unit-land on|off]",
+            "  [--cyclone-review-unit-land on|off] [--vortex-seam on|off]",
+            "  With flags: PATCH those settings and print the stored result",
+        ],
+        async run(args, ctx) {
+            await cmdSettings(args, { mode: ctx.mode });
+        },
+    },
+    {
+        name: "skill",
+        summary: "Install mergestorm-review and mergestorm-pr-loop for Claude or Cursor",
+        usage: [
+            "mergestorm skill install --claude|--cursor  Copy the mergestorm-review and mergestorm-pr-loop skills into this repo",
+            "  [--json]",
+        ],
         async run(args) {
-            await cmdWhoami(args);
+            await cmdSkill(args);
         },
     },
     {
@@ -130,12 +191,24 @@ export const COMMAND_REGISTRY = [
                     ? "usage: thread <slug>"
                     : "usage: mergestorm thread <slug>");
             }
-            await cmdThread(args[0], args.slice(1));
+            await cmdThread(args[0], args.slice(1), { mode: ctx.mode });
+        },
+    },
+    {
+        name: "queue",
+        summary: "Merge queue: list, add a stack, or remove an entry",
+        usage: [
+            "mergestorm queue [list] [--json]  List live merge-queue entries",
+            "mergestorm queue add <stack-id> [--json]  Queue a stack for verified landing",
+            "mergestorm queue rm <entry-id|stack-id> [--json]  Remove a live queue entry",
+        ],
+        async run(args) {
+            await cmdQueue(args);
         },
     },
     {
         name: "stack",
-        summary: "Stacks: create, submit, list, adopt, restack, land",
+        summary: "Stacks: /stack how-to, list yours, create → submit",
         usage: [
             "mergestorm stack create [name]  New local stack layer ([--onto] [--trunk] [--extend])",
             "mergestorm stack submit         Push active local stack, open PRs ([--extend])",
@@ -144,7 +217,6 @@ export const COMMAND_REGISTRY = [
             "mergestorm stack adopt <owner/repo>#<pr>  Import an existing open PR chain",
             "mergestorm stack restack <stack-id>   Restack stack descendants",
             "mergestorm stack land <stack-id>      Land bottom PR (or promote into unit)",
-            "mergestorm stack auto-promote on|off <stack-id>  Toggle auto-promote when green",
         ],
         async run(args) {
             await cmdStack(args);
@@ -163,7 +235,7 @@ export const COMMAND_REGISTRY = [
 ];
 /** Shell meta commands (not dispatched via {@link COMMAND_REGISTRY}). */
 const SHELL_META = [
-    { name: "help", summary: "Show available commands" },
+    { name: "help", summary: "Tabbed help (Start / Commands / Stacks)" },
     { name: "clear", summary: "Clear screen and reprint banner" },
     { name: "exit", summary: "Leave the shell" },
     { name: "quit", summary: "Leave the shell" },
@@ -176,7 +248,10 @@ export function findCommand(name) {
 }
 /** Autocomplete / `/help` list for the interactive shell. Aliases fold onto the primary name. */
 export function shellCommandSpecs() {
-    const specs = [{ name: "help", summary: SHELL_META[0].summary }];
+    const specs = [
+        { name: "help", summary: SHELL_META[0].summary },
+        { name: "exit", summary: SHELL_META[2].summary, aliases: ["quit"] },
+    ];
     for (const c of COMMAND_REGISTRY) {
         if (SHELL_OMIT.has(c.name))
             continue;
@@ -186,7 +261,7 @@ export function shellCommandSpecs() {
             ...(c.aliases?.length ? { aliases: c.aliases } : {}),
         });
     }
-    specs.push({ name: "clear", summary: SHELL_META[1].summary }, { name: "exit", summary: SHELL_META[2].summary, aliases: ["quit"] });
+    specs.push({ name: "clear", summary: SHELL_META[1].summary });
     return specs;
 }
 export function formatUsageBody() {

package/dist/commands/review-client.d.ts

@@ -1,3 +1,4 @@
+import { type PrVortexReview } from "../api.js";
 import type { Config } from "../config.js";
 import type { ReviewJobRow } from "../ui/job-envelope.js";
 export declare const REVIEW_POLL_INTERVAL_MS = 2000;
@@ -76,6 +77,13 @@ export declare class ReviewPollTimeoutError extends Error {
     readonly lastRow: ReviewJobRow;
     constructor(jobId: string, lastRow: ReviewJobRow);
 }
+export declare class PrReviewPollTimeoutError extends Error {
+    readonly owner: string;
+    readonly repo: string;
+    readonly prNumber: number;
+    readonly lastEnvelope: PrVortexReview | null;
+    constructor(owner: string, repo: string, prNumber: number, lastEnvelope: PrVortexReview | null);
+}
 export type PollReviewOptions = {
     timeoutMs?: number;
     intervalMs?: number;
@@ -90,4 +98,9 @@ export type PollReviewOptions = {
     /** Test seam for backoff jitter; production uses `Math.random`. */
     random?: () => number;
 };
+export type PollPrVortexReviewOptions = PollReviewOptions & {
+    afterSha?: string;
+};
+/** Poll the DB-only PR review endpoint until the requested pass is resting. */
+export declare function pollPrVortexReview(cfg: Config, owner: string, repo: string, prNumber: number, opts?: PollPrVortexReviewOptions): Promise<PrVortexReview>;
 export declare function pollReview(cfg: Config, jobId: string, opts?: PollReviewOptions): Promise<ReviewJobRow>;

package/dist/commands/review-client.js

@@ -210,6 +210,116 @@ export class ReviewPollTimeoutError extends Error {
         this.lastRow = lastRow;
     }
 }
+export class PrReviewPollTimeoutError extends Error {
+    owner;
+    repo;
+    prNumber;
+    lastEnvelope;
+    constructor(owner, repo, prNumber, lastEnvelope) {
+        super(`Timed out waiting for PR review ${owner}/${repo}#${prNumber}`);
+        this.name = "PrReviewPollTimeoutError";
+        this.owner = owner;
+        this.repo = repo;
+        this.prNumber = prNumber;
+        this.lastEnvelope = lastEnvelope;
+    }
+}
+function shaMatches(actual, expected) {
+    const left = actual?.trim().toLowerCase() ?? "";
+    const right = expected.trim().toLowerCase();
+    return Boolean(left && right.length >= 7 && (left.startsWith(right) || right.startsWith(left)));
+}
+/** Poll the DB-only PR review endpoint until the requested pass is resting. */
+export async function pollPrVortexReview(cfg, owner, repo, prNumber, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? REVIEW_POLL_DEFAULT_TIMEOUT_MS;
+    const intervalMs = opts.intervalMs ?? REVIEW_POLL_INTERVAL_MS;
+    const now = opts.now ?? Date.now;
+    const wait = opts.sleep ?? sleep;
+    const startedAt = now();
+    const deadline = startedAt + timeoutMs;
+    const query = new URLSearchParams({
+        owner,
+        repo,
+        pr_number: String(prNumber),
+    });
+    if (opts.afterSha)
+        query.set("after_sha", opts.afterSha);
+    let transientFailures = 0;
+    let lastEnvelope = null;
+    const sleepBeforeRetry = async (retryAfterSeconds) => {
+        const waitMs = Math.min(transientRetryWaitMs({
+            retryAfterSeconds,
+            failureCount: transientFailures,
+            random: opts.random,
+        }), Math.max(0, deadline - now()));
+        if (waitMs > 0)
+            await wait(waitMs, opts.signal);
+    };
+    const sleepBeforePoll = async () => {
+        const waitMs = Math.min(stretchedPollIntervalMs(now() - startedAt, intervalMs), Math.max(0, deadline - now()));
+        if (waitMs > 0)
+            await wait(waitMs, opts.signal);
+    };
+    while (now() < deadline) {
+        let poll;
+        try {
+            poll = await apiFetch(cfg, `/api/v1/stacks/pr-review?${query.toString()}`, {
+                signal: opts.signal,
+                timeoutMs: Math.max(1, Math.min(30_000, deadline - now())),
+            });
+        }
+        catch (err) {
+            if (isTransientReviewPollError(err) &&
+                transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
+                transientFailures += 1;
+                opts.onTick?.("retry");
+                await sleepBeforeRetry();
+                continue;
+            }
+            if (isCommandErrorCode(err, "api_timeout")) {
+                if (opts.propagateTimeout)
+                    throw err;
+                break;
+            }
+            if (isTransientReviewPollError(err)) {
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new CommandError(`Poll failed: ${detail}`, REVIEW_EXIT.failed, "review_failed");
+            }
+            throw err;
+        }
+        if (poll.status === 404) {
+            transientFailures = 0;
+            opts.onTick?.("progress");
+            await sleepBeforePoll();
+            continue;
+        }
+        if (poll.status !== 200) {
+            if (isTransientReviewPollStatus(poll.status) &&
+                transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
+                transientFailures += 1;
+                opts.onTick?.("retry");
+                await sleepBeforeRetry(poll.retryAfterSeconds);
+                continue;
+            }
+            if (poll.status === 429) {
+                throw new CommandError(rateLimitedMessage(poll.retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds: poll.retryAfterSeconds });
+            }
+            throw new CommandError(`Poll failed: ${JSON.stringify(poll.body, null, 2)}`, REVIEW_EXIT.failed, "review_failed");
+        }
+        transientFailures = 0;
+        if (!poll.body || typeof poll.body !== "object") {
+            throw new CommandError("Poll failed: invalid PR review response", REVIEW_EXIT.failed, "review_failed");
+        }
+        lastEnvelope = poll.body;
+        const resting = (lastEnvelope.raw_status ?? lastEnvelope.status) !== "in_progress";
+        const matches = !opts.afterSha || shaMatches(lastEnvelope.head_sha, opts.afterSha);
+        if (resting && matches)
+            return lastEnvelope;
+        opts.onTick?.("progress");
+        await sleepBeforePoll();
+    }
+    throw new PrReviewPollTimeoutError(owner, repo, prNumber, lastEnvelope);
+}
 export async function pollReview(cfg, jobId, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? REVIEW_POLL_DEFAULT_TIMEOUT_MS;
     const intervalMs = opts.intervalMs ?? REVIEW_POLL_INTERVAL_MS;

package/dist/commands/review.d.ts

@@ -7,6 +7,12 @@ export declare const VORTEX_ROUTER_CAPS: {
     readonly standard: 3;
     readonly max: 5;
 };
+/**
+ * Pinnable L0 lanes only. Keep this list byte-identical to
+ * `pinnableVortexSpecialistIds(VORTEX_SPECIALIST_IDS)` in review-findings
+ * (`cli-lockstep.test.ts`). Do not add `governance` (round-gated) or `seam`
+ * (phase-gated). Those L1 lanes are not local pins.
+ */
 export declare const VORTEX_SPECIALIST_IDS: readonly ["security", "performance", "architecture", "tests", "data", "api", "frontend"];
 type VortexRouterMode = (typeof VORTEX_ROUTER_MODES)[number];
 type VortexSpecialistId = (typeof VORTEX_SPECIALIST_IDS)[number];