mergestorm 0.3.9 → 0.3.13

package/README.md

@@ -28,7 +28,7 @@ After install, both `mergestorm` and `mg` invoke the same CLI.
 ## Source
 
 Public source (MIT): [github.com/marginsystems/mergestorm-cli](https://github.com/marginsystems/mergestorm-cli).
-Tags there match npm versions (`v0.3.9`, …). Clone, install, and build:
+Tags there match npm versions (`v0.3.13`, …). Clone, install, and build:
 
 ```bash
 git clone https://github.com/marginsystems/mergestorm-cli.git
@@ -44,13 +44,13 @@ node dist/cli.js --help
 On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a **full-width** welcome panel (logo + status on the left, tips / what's new on the right) and a **full-width** bordered input box with a live `/` slash-command dropdown. Non-TTY (CI/pipes) prints usage instead — no hanging prompt.
 
 ```
-╭─ mergestorm v0.3.9 ──────────────────────────────────────────────────────────╮
+╭─ mergestorm v0.3.13 ─────────────────────────────────────────────────────────╮
 │      ▟██████████▛       Tips for getting started                             │
 │       ▜████████▛          review      review origin/HEAD or main             │
 │        ▝▜████▛▘           stack       create → submit → restack → land       │
 │          ▜██▛             /help       list all commands                      │
 │           ██                                                                 │
-│           ▝▘            What's new in v0.3.9                                 │
+│           ▝▘            What's new in v0.3.13                                │
 │  ● msk…  ·  maelstrom     • MIT license + public source (mergestorm-cli)       │
 │  [████░░░░░░░░░░] 12% used                                                   │
 ╰──────────────────────────────────────────────────────────────────────────────╯
@@ -66,9 +66,9 @@ mergestorm> chain
 mergestorm> exit
 ```
 
-Bare command names still work exactly as before (`review`, `help`, `exit`, …) — typing `/` at the start of a line just opens the live autocomplete dropdown (filtered as you type, navigate with Up/Down, accept with Tab/Enter/Right). Arrow-key history, Ctrl+A/E, Ctrl+U/K work as in a regular shell. At the idle prompt, **Ctrl+C twice** (within ~1.5s) exits the shell; a single Ctrl+C clears the line and shows a confirm hint. While `review` / `status` is waiting, Ctrl+C detaches or aborts that wait (job may keep running) — it does not exit the shell. Ctrl+D on an empty line, or `exit` / `quit`, also leave the shell. On a dumb terminal, without color, or when piped, the box falls back to plain ASCII borders (or no shell at all for non-TTY input).
+Bare command names still work exactly as before (`review`, `help`, `exit`, …) — typing `/` at the start of a line opens a compact autocomplete overlay (aliases folded onto the primary name, Up/Down scroll a viewport, Esc dismisses, Tab completes, Enter accepts a prefix or submits an exact name as typed, Left/Right move the cursor). Arrow-key history, Ctrl+A/E, Ctrl+U/K work as in a regular shell. At the idle prompt, **Ctrl+C twice** (within ~1.5s) exits the shell; a single Ctrl+C clears the line and shows a confirm hint. While `review` / `status` is waiting, Ctrl+C detaches or aborts that wait (job may keep running) — it does not exit the shell. Ctrl+D on an empty line, or `exit` / `quit`, also leave the shell. On a dumb terminal, without color, or when piped, the box falls back to plain ASCII borders (or no shell at all for non-TTY input).
 
-`credits` / `usage` print a usage meter — long bar + `N% used`, then `Resets … (UTC)` — for standard and premium. `branches` (alias `chains`) lists recently reviewed branches; on a TTY you arrow-select one to open its review-chain timeline. `chain [slug]` shows that timeline directly (defaults to `local/<current-git-branch>`).
+`credits` / `usage` print one static panel: key · plan, a credit bar sized to the terminal, `Resets … (UTC)`, then the last five jobs. `--json` adds `recent_jobs`. `branches` (alias `chains`) lists recently reviewed branches; on a TTY you arrow-select one to open its review-chain timeline. `chain [slug]` shows that timeline directly (defaults to `local/<current-git-branch>`).
 
 ## Commands
 
@@ -81,15 +81,15 @@ mergestorm login                Sign in via browser; stores an API key in ~/.mer
 mergestorm login --key          Paste an existing API key instead (headless/CI)
 mergestorm logout               Remove the stored API key
 mergestorm review [base] [head] Review git diff base...head (default: origin/HEAD or main or master)
-mergestorm status <job_id>      Fetch a review job and print JSON (one shot)
-mergestorm credits [--json]     Standard + premium credit balance (usage bars)
+mergestorm status <job_id>      Fetch a review job (envelope; --json --wait --timeout)
+mergestorm credits [--json]     Usage panel (bar + last 5 jobs)
 mergestorm jobs [n] [--json]    Recent review jobs (default 10, max 50)
 mergestorm branches [n]         Recently reviewed branches (arrow-pick on TTY)
 mergestorm chain [slug]         Branch review-chain timeline (default: current branch)
 mergestorm whoami [--json]      Key prefix, plan, API base, config path
 mergestorm thread <slug>        Jobs in a review thread
-mergestorm stack create [name]  New local stack layer (optional `--onto` / `--trunk`)
-mergestorm stack submit         Push layers, open chained PRs (`gh`), register via adopt
+mergestorm stack create [name]  New local stack layer (optional `--onto` / `--trunk` / `--extend`)
+mergestorm stack submit         Push layers, open PRs (`gh`), register via adopt (optional `--extend`)
 mergestorm stack list [--json]  List registered stacks
 mergestorm stack adopt <owner/repo>#<pr>  Import an existing open PR chain
 mergestorm stack restack <stack-id>  Restack descendants
@@ -100,7 +100,9 @@ mergestorm stack reset --force  Clear local authoring state (not branches/PRs)
 
 `mg` is a short alias for `mergestorm` (same binary), e.g. `mg stack create`. Happy path: **create → commit → submit → restack → land**. On review-unit stacks, `stack land` **promotes** the tip into the unit (same gates as the dashboard); otherwise it lands the bottom open PR. `stack auto-promote` turns on land-when-green for a registered stack (`auto-land` remains a deprecated alias). `stack adopt` is for importing a chain that already exists on GitHub (legacy / Graphite). Restack/land use the same login key (`/api/v1/stacks`).
 
-`stack create` is local-only: it checks out a new branch from the current tip (or `--onto <branch>`), discovers trunk (`main` / `master` / `origin/HEAD`, overridable with `--trunk`), and records `{ branch, parentBranch }` in CLI-managed state under **`~/.mergestorm/stacks/<repo-id>/stack.json`**. The CLI updates this automatically; never edit it. Linked worktrees share state, while independent clones remain isolated. Creating onto trunk with a non-empty active stack starts a new one. No repository file, GitHub call, or API call is made.
+`stack create` checks out a new branch from the current tip (or `--onto <branch>`), discovers trunk (`main` / `master` / `origin/HEAD`, overridable with `--trunk`), and records `{ branch, parentBranch }` in CLI-managed state under **`~/.mergestorm/stacks/<repo-id>/stack.json`**. The CLI updates this automatically; never edit it. Linked worktrees share state, while independent clones remain isolated. Creating onto trunk with a non-empty active stack starts a new one. `--trunk` only sets trunk metadata — it does **not** change the parent; use `--onto main` (etc.) for a fresh stack from trunk.
+
+If the parent branch is already a layer of a **registered** (submitted) stack, `create` and `submit` refuse unless you pass **`--extend`**. That blocks accidentally gluing an unrelated PR onto an open unit. Growing a registered stack on purpose: `mg stack create --onto <tip> --extend` → commit → `mg stack submit --extend`.
 
 `stack submit` walks the **active** local stack: `git push -u origin` each layer, opens a PR with `gh` (`--base` = parent or trunk; skips heads that already have an open PR; body from the tip commit — Summary + Test plan, preserving Fixes/Closes/Resolves), registers the stack with `POST /api/v1/stacks/adopt` internally (Mergestorm API key), then drops that local stack entry so the next create onto trunk is clean. Push/PR auth is your local `git` + `gh auth` — not a GitHub App installation token.
 
@@ -118,19 +120,38 @@ Removes `~/.mergestorm/config.json` so the stored key is no longer used.
 
 ### `review [base] [head]`
 
-Collects `git diff base...head` (default: discovered trunk — `origin/HEAD`, `main`, or `master`), attaches the changed file contents (up to 40 files, skipping files > 400 KB), submits the job, and polls until it finishes (~3 min max). The thread slug is derived from the current branch (`local/<branch>`), so repeated runs on the same branch chain their findings. Programmatic callers can provide explicit review context through the Review Jobs API.
+Collects `git diff base...head` (default: discovered trunk — `origin/HEAD`, `main`, or `master`), attaches the changed file contents (up to 40 files, skipping files > 400 KB), submits the job, and polls until it finishes (~8 min max — Core plus a Max fleet can exceed 3 minutes). The thread slug defaults to the current branch (`local/<branch>`); pass `--thread` to override so follow-ups chain on a chosen slug. The CLI does not scan `.mergestorm/context/`.
 
 ```bash
 mergestorm review              # discovered trunk (origin/HEAD, main, or master)...HEAD
 mergestorm review develop      # develop...HEAD
 mergestorm review main feat/x  # main...feat/x
+mergestorm review main --router max
+mergestorm review main --router manual --specialists security,frontend
+mergestorm review --json --context "focus on auth" --context-file docs/adr/007.md
 ```
 
-Exit code is non-zero on quota limit (402), submission failure, a `failed`/`quota_exceeded` job, or a poll timeout. In the interactive shell, Ctrl+C during the wait detaches (job keeps running) — use `status <job_id>` later.
+`--router` is the same smart-router mode as Agents settings (`off` / `standard` / `max` / `manual`). `--specialists` pins or invokes lanes on that request (comma-separated). Omit both to use the signed-in user's saved fleet settings (paid default is Standard, same as the dashboard). Manual accepts up to 5 lane ids — the same cap as Agents (the smart router caps `standard` at 3 and `max` at 5).
+
+`--context` is author guidance (or `--context -` to read stdin). `--context-file` is repeatable up to 10 files (16 KB each, 60 KB total). `--idempotency-key` replays a prior 202 for the same key. `--webhook-url` must be https; the one-time `webhook_secret` is printed only in `--json` output. Webhook delivery is best-effort (no retry).
+
+Exit codes for `review` and `status`:
+
+| Exit | Meaning |
+|------|---------|
+| 0 | Success (`completed` or `no_changes`) |
+| 2 | Usage / bad flags |
+| 3 | Quota (`402` or `quota_exceeded`) |
+| 4 | Failed job or other submission error |
+| 5 | Poll / request timeout |
+| 6 | Auth (missing or invalid API key) |
+| 7 | Rate limited (`429`) — wait `retry_after_seconds`, or check a running review with `mergestorm jobs` / `status` |
+
+In the interactive shell, Ctrl+C during the wait detaches (job keeps running) — use `status <job_id>` later.
 
 ### `status <job_id>`
 
-Fetches a job by id and prints the raw JSON (status, verdict, summary, findings). In the shell, output is formatted for reading.
+Fetches a job by id. One-shot default (and `--json` in either mode) prints the same `mergestorm.review_job/v1` object as `review --json`. `--wait [--timeout seconds]` polls until the job finishes; timeout is exit 5 with the id in the object. In the shell, default output is pretty (requested vs run specialists and credits).
 
 ### `credits` / `jobs` / `whoami`
 
@@ -148,6 +169,29 @@ Require a logged-in key and API support for `GET /api/v1/me` and `GET /api/v1/re
 | `MERGESTORM_API_URL` | API base URL | `https://api.mergestorm.ai` |
 | `NO_COLOR` | Disable ANSI colors | — |
 
+## Verify (public source vs npm)
+
+Build **only** from [marginsystems/mergestorm-cli](https://github.com/marginsystems/mergestorm-cli). Tags there (`vX.Y.Z`) match npm versions. Compare your local pack to the registry hashes below (or `npm view mergestorm@VERSION dist`).
+
+| npm | Public git tag | Public commit | npm `dist.shasum` (sha1) | npm `dist.integrity` |
+|-----|----------------|---------------|--------------------------|----------------------|
+| `0.3.9` | [`v0.3.9`](https://github.com/marginsystems/mergestorm-cli/tree/v0.3.9) | `89eaebc29cf793db52baf3e9af0f2bed6e42e458` | `f904f4f642a07c0f9716fe36ed9e5a813be47530` | `sha512-zkbEhwkog13xC70LcM77bWFzLTyoE7Q81daaxz/1Gk3IqVyEoyhKpR+PAtfTp+Mk3MqJ7yVhvZ8/9UG4hpT/Dw==` |
+
+```bash
+git clone https://github.com/marginsystems/mergestorm-cli.git
+cd mergestorm-cli
+git checkout v0.3.9
+git rev-parse HEAD   # expect 89eaebc29cf793db52baf3e9af0f2bed6e42e458
+npm ci
+npm run build
+npm pack
+shasum -a 1 mergestorm-0.3.9.tgz
+# expect f904f4f642a07c0f9716fe36ed9e5a813be47530
+# also: npm view mergestorm@0.3.9 dist.shasum dist.integrity
+```
+
+After each release, the new row’s git commit is the public `v*` tag tip; shasum/integrity come from the npm registry for that version.
+
 ## See also
 
 - [Public source — mergestorm-cli](https://github.com/marginsystems/mergestorm-cli)

package/dist/api.d.ts

@@ -1,4 +1,6 @@
 import { type Config } from "./config.js";
+import type { StackDto } from "./stack-dto.js";
+export type { StackBranchState, StackCiStatus, StackDto, StackLayerChecks, StackLayerDto, StackReviewStatus, StackTempestStatus, StackUnitDto, StackUnitMemberDto, } from "./stack-dto.js";
 /** Default per-request timeout so a hung API cannot stall the shell/CI forever. */
 export declare const DEFAULT_API_TIMEOUT_MS = 30000;
 /** Message prefix of the CommandError thrown when a request exceeds its timeout. */
@@ -8,10 +10,17 @@ export type ApiFetchInit = RequestInit & {
     /** Override {@link DEFAULT_API_TIMEOUT_MS}. */
     timeoutMs?: number;
 };
-export declare function apiFetch(cfg: Config, route: string, init?: ApiFetchInit): Promise<{
+export type ApiFetchResult = {
     status: number;
     body: unknown;
-}>;
+    retryAfterSeconds?: number;
+};
+/** Prefer the larger of `Retry-After` and JSON `retry_after_seconds`. */
+export declare function parseRetryAfterSeconds(input: {
+    header?: string | null;
+    body?: unknown;
+}): number | undefined;
+export declare function apiFetch(cfg: Config, route: string, init?: ApiFetchInit): Promise<ApiFetchResult>;
 export declare function devicePost(base: string, route: string, json: unknown, opts?: {
     timeoutMs?: number;
     signal?: AbortSignal;
@@ -28,7 +37,7 @@ export type MeResponse = {
     };
     plan_key: string;
     plan_label_key?: string;
-    /** Start of next UTC month (usage meters reset). Older APIs omit this. */
+    /** When the current credit window ends (signup anniversary or Stripe period). Older APIs omit this. */
     resets_at?: string;
     usage: {
         standard: {
@@ -36,11 +45,6 @@ export type MeResponse = {
             limit: number | null;
             remaining: number | null;
         };
-        premium: {
-            used: number;
-            limit: number | null;
-            remaining: number | null;
-        };
     };
 };
 export type JobListItem = {
@@ -53,7 +57,9 @@ export type JobListItem = {
     head_label: string | null;
     created_at: string;
     finished_at: string | null;
-    credits: number;
+    credits: {
+        standard: number;
+    } | null;
 };
 export type ThreadListItem = {
     slug: string;
@@ -93,38 +99,21 @@ export declare function getMe(cfg?: Config, opts?: {
     timeoutMs?: number;
 }): Promise<MeResponse | null>;
 export declare function listJobs(limit?: number, cfg?: Config): Promise<JobListItem[]>;
-export type StackLayerDto = {
-    branch: string;
-    parentBranch: string | null;
-    prNumber: number;
-    position: number;
-    state: string;
-    title: string | null;
-    htmlUrl: string | null;
-    ciStatus: string;
-    reviewStatus: string;
-    checks: {
-        total: number;
-        success: number;
-        pending: number;
-        failure: number;
-        failingName: string | null;
-    } | null;
-    conflictDetail: string | null;
-    lastRestackedSha: string | null;
-};
-export type StackDto = {
-    id: string;
-    owner: string;
-    repo: string;
-    trunkBranch: string;
-    autoPromoteWhenGreen: boolean;
-    layers: StackLayerDto[];
-};
+/** Fetch one review job (Bearer GET /api/v1/reviews/:id). */
+export declare function getReview(jobId: string, cfg?: Config, opts?: {
+    signal?: AbortSignal;
+}): Promise<unknown>;
 /** List stacks (Bearer GET /api/v1/stacks). */
-export declare function listStacks(cfg?: Config): Promise<StackDto[]>;
+export declare function listStacks(cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<StackDto[]>;
 /** Adopt an open PR chain (Bearer POST /api/v1/stacks/adopt). */
 export declare function adoptStack(owner: string, repo: string, prNumber: number, cfg?: Config): Promise<unknown>;
+/** Mint or reuse the PR3+ park freeze (Bearer POST /api/v1/stacks/:id/ensure-upper-park). */
+export declare function ensureUpperPark(stackId: string, cfg?: Config): Promise<{
+    freezeBranch: string;
+    created: boolean;
+}>;
 /** Restack descendants (Bearer POST /api/v1/stacks/:id/restack). */
 export declare function restackStack(stackId: string, cfg?: Config): Promise<unknown>;
 /** Land the bottom open layer (Bearer POST /api/v1/stacks/:id/land-next). */

package/dist/api.js

@@ -1,9 +1,42 @@
 import { apiBase, loadConfig, resolveApiKey } from "./config.js";
-import { CommandError } from "./errors.js";
+import { CommandError, REVIEW_EXIT, rateLimitedMessage } from "./errors.js";
 /** Default per-request timeout so a hung API cannot stall the shell/CI forever. */
 export const DEFAULT_API_TIMEOUT_MS = 30_000;
 /** Message prefix of the CommandError thrown when a request exceeds its timeout. */
 export const API_TIMEOUT_PREFIX = "Request timed out after";
+function asPositiveSeconds(value) {
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return value;
+    }
+    if (typeof value === "string" && /^\d+(\.\d+)?$/.test(value.trim())) {
+        return Number(value.trim());
+    }
+    return undefined;
+}
+function parseRetryAfterHeader(header) {
+    if (!header)
+        return undefined;
+    const trimmed = header.trim();
+    const asNumber = asPositiveSeconds(trimmed);
+    if (asNumber !== undefined)
+        return asNumber;
+    const when = Date.parse(trimmed);
+    if (!Number.isFinite(when))
+        return undefined;
+    return Math.max(0, (when - Date.now()) / 1000);
+}
+/** Prefer the larger of `Retry-After` and JSON `retry_after_seconds`. */
+export function parseRetryAfterSeconds(input) {
+    const fromBody = input.body && typeof input.body === "object"
+        ? asPositiveSeconds(input.body.retry_after_seconds)
+        : undefined;
+    const fromHeader = parseRetryAfterHeader(input.header);
+    if (fromBody === undefined)
+        return fromHeader;
+    if (fromHeader === undefined)
+        return fromBody;
+    return Math.max(fromBody, fromHeader);
+}
 function isAbortLike(err) {
     return (err instanceof Error &&
         (err.name === "AbortError" || err.name === "TimeoutError"));
@@ -82,7 +115,15 @@ export async function apiFetch(cfg, route, init = {}) {
     if (res.status === 401) {
         throw new CommandError("API key invalid or revoked. Run `mergestorm login`.", 1, "auth_invalid");
     }
-    return { status: res.status, body: parsed };
+    const retryAfterSeconds = parseRetryAfterSeconds({
+        header: res.headers.get("retry-after"),
+        body: parsed,
+    });
+    return {
+        status: res.status,
+        body: parsed,
+        ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+    };
 }
 export async function devicePost(base, route, json, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_API_TIMEOUT_MS;
@@ -150,10 +191,31 @@ export async function listJobs(limit = 10, cfg) {
     const items = body.items;
     return Array.isArray(items) ? items : [];
 }
+/** Fetch one review job (Bearer GET /api/v1/reviews/:id). */
+export async function getReview(jobId, cfg, opts) {
+    const resolved = cfg ?? (await loadConfig());
+    const id = jobId.trim();
+    if (!id) {
+        throw new CommandError("job_id is required", 2, "usage");
+    }
+    const { status, body, retryAfterSeconds } = await apiFetch(resolved, `/api/v1/reviews/${encodeURIComponent(id)}`, { signal: opts?.signal });
+    if (status === 404) {
+        throw new CommandError(`Review not found: ${id}`);
+    }
+    if (status === 429) {
+        throw new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds });
+    }
+    if (status !== 200) {
+        throw new CommandError(`Failed to get review (HTTP ${status}): ${JSON.stringify(body)}`);
+    }
+    return body;
+}
 /** List stacks (Bearer GET /api/v1/stacks). */
-export async function listStacks(cfg) {
+export async function listStacks(cfg, opts) {
     const resolved = cfg ?? (await loadConfig());
-    const { status, body } = await apiFetch(resolved, "/api/v1/stacks");
+    const { status, body } = await apiFetch(resolved, "/api/v1/stacks", {
+        timeoutMs: opts?.timeoutMs,
+    });
     if (status === 404) {
         throw new CommandError("Stacks API is not available on this server yet. Deploy the API update or use the dashboard.");
     }
@@ -178,6 +240,21 @@ export async function adoptStack(owner, repo, prNumber, cfg) {
     }
     return body;
 }
+/** Mint or reuse the PR3+ park freeze (Bearer POST /api/v1/stacks/:id/ensure-upper-park). */
+export async function ensureUpperPark(stackId, cfg) {
+    const body = await stackMutation(stackId, "/ensure-upper-park", "POST", {}, "Failed to ensure upper-park freeze", cfg);
+    if (typeof body !== "object" || body === null) {
+        throw new CommandError("Unexpected response shape from ensure-upper-park");
+    }
+    const freezeBranch = body.freezeBranch;
+    if (typeof freezeBranch !== "string" || !freezeBranch.trim()) {
+        throw new CommandError("ensure-upper-park did not return a freezeBranch");
+    }
+    return {
+        freezeBranch: freezeBranch.trim(),
+        created: body.created === true,
+    };
+}
 async function stackMutation(stackId, pathSuffix, method, json, failLabel, cfg) {
     const resolved = cfg ?? (await loadConfig());
     const { status, body } = await apiFetch(resolved, `/api/v1/stacks/${encodeURIComponent(stackId)}${pathSuffix}`, method === "PATCH"

package/dist/client/index.d.ts

@@ -0,0 +1,5 @@
+export { DEFAULT_API, apiBase, clearConfig, configPath, keyDisplay, loadConfig, mergestormHome, resolveApiKey, saveConfig, type Config, } from "../config.js";
+export { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, adoptStack, apiFetch, devicePost, ensureUpperPark, getMe, getReview, landNextStack, listJobs, listStacks, listThreads, parseRetryAfterSeconds, restackStack, setStackAutoPromote, type ApiFetchInit, type ApiFetchResult, type JobListItem, type MeResponse, type ThreadDetail, type ThreadListItem, } from "../api.js";
+export { CommandError, DetachedError, RATE_LIMITED_HINT, REVIEW_EXIT, isCommandErrorCode, rateLimitedMessage, type CommandErrorCode, type CommandErrorExtras, } from "../errors.js";
+export { REVIEW_POLL_BACKOFF_MS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_POLL_STRETCH_AFTER_MS, REVIEW_POLL_STRETCH_SPAN_MS, REVIEW_THREAD_SLUG_RE, ReviewPollTimeoutError, collectReviewInput, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, type PollReviewOptions, type ReviewInput, type SubmitReviewOptions, } from "../commands/review-client.js";
+export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, type ReviewEnvelopeFallbacks, type ReviewJobEnvelope, type ReviewJobRow, } from "../ui/job-envelope.js";

package/dist/client/index.js

@@ -0,0 +1,5 @@
+export { DEFAULT_API, apiBase, clearConfig, configPath, keyDisplay, loadConfig, mergestormHome, resolveApiKey, saveConfig, } from "../config.js";
+export { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, adoptStack, apiFetch, devicePost, ensureUpperPark, getMe, getReview, landNextStack, listJobs, listStacks, listThreads, parseRetryAfterSeconds, restackStack, setStackAutoPromote, } from "../api.js";
+export { CommandError, DetachedError, RATE_LIMITED_HINT, REVIEW_EXIT, isCommandErrorCode, rateLimitedMessage, } from "../errors.js";
+export { REVIEW_POLL_BACKOFF_MS, REVIEW_POLL_DEFAULT_TIMEOUT_MS, REVIEW_POLL_INTERVAL_MS, REVIEW_POLL_MAX_INTERVAL_MS, REVIEW_POLL_MAX_TRANSIENT_RETRIES, REVIEW_POLL_STRETCH_AFTER_MS, REVIEW_POLL_STRETCH_SPAN_MS, REVIEW_THREAD_SLUG_RE, ReviewPollTimeoutError, collectReviewInput, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, } from "../commands/review-client.js";
+export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, } from "../ui/job-envelope.js";

package/dist/commands/credits.js

@@ -1,8 +1,18 @@
-import { getMe } from "../api.js";
+import { getMe, listJobs } from "../api.js";
 import { loadConfig } from "../config.js";
 import { CommandError } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
-import { formatResetLabel, usageBar } from "../ui/usage.js";
+import { formatUsagePanel } from "../ui/usage.js";
+import { relativeWhen } from "./jobs.js";
+function toPanelJob(job) {
+    return {
+        job: job.job_id.slice(0, 8),
+        verdict: job.verdict ?? job.status ?? "-",
+        thread: job.thread_slug ?? "-",
+        credits: job.credits ? String(job.credits.standard) : "-",
+        when: relativeWhen(job.created_at),
+    };
+}
 export async function cmdCredits(args) {
     const asJson = args.includes("--json");
     const cfg = await loadConfig();
@@ -11,18 +21,29 @@ export async function cmdCredits(args) {
         throw new CommandError("Credits are not available (not logged in, offline, or API too old). " +
             "Try `mergestorm login` or open https://mergestorm.ai/billing");
     }
+    let recentJobs = [];
+    try {
+        recentJobs = await listJobs(5, cfg);
+    }
+    catch {
+        recentJobs = [];
+    }
     if (asJson) {
-        console.log(JSON.stringify({ usage: me.usage, resets_at: me.resets_at ?? null }, null, 2));
+        console.log(JSON.stringify({ usage: me.usage, resets_at: me.resets_at ?? null, recent_jobs: recentJobs }, null, 2));
         return;
     }
     const s = me.usage.standard;
-    const p = me.usage.premium;
-    // Claude Usage tab layout: label → long bar + "N% used" → Resets line.
-    console.log(`  ${ansi.bold("Standard")}`);
-    console.log(`  ${usageBar(s.used, s.limit)}`);
-    console.log("");
-    console.log(`  ${ansi.bold("Premium")}`);
-    console.log(`  ${usageBar(p.used, p.limit)}`);
-    console.log("");
-    console.log(`  ${ansi.dim(formatResetLabel(me.resets_at))}`);
+    const columns = process.stdout.columns || 80;
+    const lines = formatUsagePanel({
+        keyPrefix: me.key.prefix,
+        plan: me.plan_label_key ?? me.plan_key,
+        used: s.used,
+        limit: s.limit,
+        resetsAt: me.resets_at,
+        jobs: recentJobs.map(toPanelJob),
+        columns,
+        color: ansi.enabled,
+    });
+    for (const line of lines)
+        console.log(line);
 }

package/dist/commands/login.js

@@ -59,13 +59,29 @@ export async function cmdLogin(args) {
     const cfg = await loadConfig();
     const base = apiBase(cfg);
     let start;
-    try {
-        start = await devicePost(base, "/api/v1/cli/device", {});
-    }
-    catch {
-        throw new CommandError("Could not start device login. The API may be unreachable or misconfigured.\n" +
-            "Run `mergestorm login --key` to paste an existing API key instead.");
-    }
+    let attempt = 0;
+    do {
+        try {
+            start = await devicePost(base, "/api/v1/cli/device", {});
+        }
+        catch {
+            throw new CommandError("Could not start device login. The API may be unreachable or misconfigured.\n" +
+                "Run `mergestorm login --key` to paste an existing API key instead.");
+        }
+        const err = start.body?.error;
+        if (err !== "rate_limited" && err !== "slow_down")
+            break;
+        if (start.status !== 429 && start.status !== 400)
+            break;
+        const backoff = Number(start.body?.retry_after_seconds);
+        const waitMs = Number.isFinite(backoff) && backoff > 0 ? backoff * 1000 : 5000;
+        if (attempt === 2) {
+            throw new CommandError(`Device login is rate limited for this IP. Wait ${Math.ceil(waitMs / 1000)}s, then run \`mergestorm login\` again.`);
+        }
+        console.log(`Device login is rate limited. Waiting ${Math.ceil(waitMs / 1000)}s before trying again…`);
+        await new Promise((r) => setTimeout(r, waitMs));
+        attempt += 1;
+    } while (attempt < 3);
     if (start.status !== 200 || !start.body?.device_code) {
         throw new CommandError(`Could not start device login (HTTP ${start.status}). The API may be unreachable or misconfigured.\n` +
             `Run \`mergestorm login --key\` to paste an existing API key instead.`);
@@ -100,6 +116,11 @@ export async function cmdLogin(args) {
             process.stdout.write(".");
             continue;
         }
+        if (err === "slow_down" || err === "rate_limited") {
+            const backoff = Number(poll.body?.retry_after_seconds);
+            await new Promise((r) => setTimeout(r, Number.isFinite(backoff) && backoff > 0 ? backoff * 1000 : pollMs));
+            continue;
+        }
         if (err === "key_limit_reached") {
             throw new CommandError("You have reached the max active API keys. Revoke one at https://mergestorm.ai/settings#api and try again.");
         }

package/dist/commands/registry.d.ts

@@ -22,7 +22,7 @@ export type RegistryCommand = {
  */
 export declare const COMMAND_REGISTRY: RegistryCommand[];
 export declare function findCommand(name: string): RegistryCommand | undefined;
-/** Autocomplete / `/help` list for the interactive shell. */
+/** Autocomplete / `/help` list for the interactive shell. Aliases fold onto the primary name. */
 export declare function shellCommandSpecs(): CommandSpec[];
 export declare function formatUsageBody(): string;
 /**

package/dist/commands/registry.js

@@ -41,7 +41,12 @@ export const COMMAND_REGISTRY = [
         name: "review",
         summary: "Review git diff (default origin/HEAD or main or master)",
         usage: [
-            "mergestorm review [base] [head] Review git diff base...head (default: origin/HEAD or main or master)",
+            "mergestorm review [base] [head] Review git diff base...head",
+            "  [--json] [--wait|--no-wait] [--timeout seconds]",
+            "  [--router off|standard|max|manual] [--specialists id,id]",
+            "  [--context text] [--context-file path] [--thread slug]",
+            "  [--idempotency-key k] [--webhook-url https://…]",
+            "  HTTP 429 exits 7 (rate_limited) with retry_after_seconds",
         ],
         async run(args, ctx) {
             if (ctx.mode === "shell") {
@@ -55,26 +60,27 @@ export const COMMAND_REGISTRY = [
         name: "status",
         summary: "Show a review job",
         usage: [
-            "mergestorm status <job_id>      Fetch a review job and print JSON (one shot)",
+            "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",
         ],
         async run(args, ctx) {
-            if (!args[0]) {
-                throw new CommandError(ctx.mode === "shell"
-                    ? "usage: status <job_id>"
-                    : "usage: mergestorm status <job_id>");
-            }
             if (ctx.mode === "shell") {
-                await cmdStatus(args[0], { format: "pretty", signal: ctx.signal });
+                await cmdStatus(args, {
+                    defaultFormat: "pretty",
+                    signal: ctx.signal,
+                    interactive: true,
+                });
                 return;
             }
-            await cmdStatus(args[0], { format: "json" });
+            await cmdStatus(args, { defaultFormat: "json" });
         },
     },
     {
         name: "credits",
         aliases: ["usage"],
-        summary: "Credit balance with usage bars",
-        usage: ["mergestorm credits [--json]     Credit balance (usage bars)"],
+        summary: "Usage panel: credit bar and last five jobs",
+        usage: ["mergestorm credits [--json]     Usage panel (bar + last 5 jobs)"],
         async run(args) {
             await cmdCredits(args);
         },
@@ -131,8 +137,8 @@ export const COMMAND_REGISTRY = [
         name: "stack",
         summary: "Stacks: create, submit, list, adopt, restack, land",
         usage: [
-            "mergestorm stack create [name]  New local stack layer (CLI-managed authoring state)",
-            "mergestorm stack submit         Push active local stack, open PRs, register stack",
+            "mergestorm stack create [name]  New local stack layer ([--onto] [--trunk] [--extend])",
+            "mergestorm stack submit         Push active local stack, open PRs ([--extend])",
             "mergestorm stack reset --force  Clear this repo's pre-submit authoring state",
             "mergestorm stack list [--json]  List registered stacks",
             "mergestorm stack adopt <owner/repo>#<pr>  Import an existing open PR chain",
@@ -168,18 +174,19 @@ export function findCommand(name) {
     const key = name.toLowerCase();
     return COMMAND_REGISTRY.find((c) => c.name === key || (c.aliases?.includes(key) ?? false));
 }
-/** Autocomplete / `/help` list for the interactive shell. */
+/** 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 }];
     for (const c of COMMAND_REGISTRY) {
         if (SHELL_OMIT.has(c.name))
             continue;
-        specs.push({ name: c.name, summary: c.summary });
-        for (const alias of c.aliases ?? []) {
-            specs.push({ name: alias, summary: c.summary });
-        }
+        specs.push({
+            name: c.name,
+            summary: c.summary,
+            ...(c.aliases?.length ? { aliases: c.aliases } : {}),
+        });
     }
-    specs.push({ name: "clear", summary: SHELL_META[1].summary }, { name: "exit", summary: SHELL_META[2].summary }, { name: "quit", summary: SHELL_META[3].summary });
+    specs.push({ name: "clear", summary: SHELL_META[1].summary }, { name: "exit", summary: SHELL_META[2].summary, aliases: ["quit"] });
     return specs;
 }
 export function formatUsageBody() {