mergestorm 0.3.13 → 0.3.16

package/README.md

@@ -41,18 +41,16 @@ node dist/cli.js --help
 
 ## Interactive shell
 
-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.
+On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a compact **full-width** welcome panel (mark, version, status, usage bar) and a **full-width** bordered input box with a live `/` slash-command dropdown. The welcome panel reflows on terminal resize instead of wrapping or smearing. Non-TTY (CI/pipes) prints usage instead — no hanging prompt.
 
 ```
-╭─ 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.13                                │
-│  ● msk…  ·  maelstrom     • MIT license + public source (mergestorm-cli)       │
-│  [████░░░░░░░░░░] 12% used                                                   │
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ ▟██▛  mergestorm v0.3.16                                                     │
+│  ▜▙   ● msk_live_…  · maelstrom                                              │
+│       [████████░░░░░░░░░░░░░░░░░░░░░░] 25% used · Resets Sep 5, 10:53am (UTC)│
+│                                                                              │
+│       review a diff · usage for tabs · /help for all commands                │
+│       New in v0.3.16: verify findings, small diff, public dismiss on skip    │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
 ╭──────────────────────────────────────────────────────────────────────────────╮
@@ -60,7 +58,7 @@ mergestorm
 ╰──────────────────────────────────────────────────────────────────────────────╯
   /review       Review git diff (default origin/HEAD or main or master)
 
-mergestorm> credits
+mergestorm> usage
 mergestorm> branches
 mergestorm> chain
 mergestorm> exit
@@ -68,7 +66,7 @@ mergestorm> exit
 
 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 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>`).
+`credits` / `usage` on a TTY open a tabbed **Status / Usage / Jobs** browser (Usage selected): Left/Right switch tabs, Up/Down scroll or select, Enter on a job opens its `status` detail in place, Esc backs out, `q` closes. `status` with no job id opens the same browser on the Status tab. Piped / non-TTY output keeps the static panel: key · plan, a credit bar sized to the terminal, `Resets … (UTC)`, then the last five jobs; `--json` adds `recent_jobs` and is unchanged. `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
 
@@ -82,11 +80,13 @@ 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 (envelope; --json --wait --timeout)
-mergestorm credits [--json]     Usage panel (bar + last 5 jobs)
+mergestorm status               Tabbed Status / Usage / Jobs browser (TTY)
+mergestorm credits [--json]     Usage panel (bar + last 5 jobs); tabbed browser on a TTY
 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 skill install --claude|--cursor  Copy the mergestorm-review and mergestorm-pr-loop skills into this repo
 mergestorm thread <slug>        Jobs in a review thread
 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`)
@@ -94,13 +94,12 @@ 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
 mergestorm stack land <stack-id>     Land / promote (into review unit when present)
-mergestorm stack auto-promote on|off <stack-id>  Toggle auto-promote when green
 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`).
+`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 adopt` is for importing a chain that already exists on GitHub (legacy / Graphite). Restack/land use the same login key (`/api/v1/stacks`). Unattended landing is `mg queue add`.
 
-`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.
+`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. Each worktree has its own authoring state; independent clones stay isolated too. 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`.
 
@@ -120,7 +119,7 @@ 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 (~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/`.
+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 still does not scan a repo folder for review context. GitHub Vortex will read house-rule files in a later PR (`AGENTS.md`, `CLAUDE.md`, alwaysApply Cursor rules). That ingest is not shipping yet.
 
 ```bash
 mergestorm review              # discovered trunk (origin/HEAD, main, or master)...HEAD

package/dist/api.d.ts

@@ -1,6 +1,7 @@
 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";
+import { BEARER_SETTINGS_KEYS as SETTINGS_WRITABLE_KEYS, type BearerSettingsKey as SettingsWritableKey } from "./automation-catalog.js";
+import type { MergeQueueEntryDto, StackDto } from "./stack-dto.js";
+export type { MergeQueueBounceDetail, MergeQueueBounceKind, MergeQueueEnqueuedBy, MergeQueueEnqueuedVia, MergeQueueEntryDto, MergeQueueEntryState, 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. */
@@ -94,33 +95,129 @@ export type ThreadDetail = {
         finished_at?: string | null;
     }[];
 };
+export type PrReviewFinding = {
+    path?: string;
+    line?: number;
+    severity: string;
+    body: string;
+    title?: string;
+    specialist?: string;
+};
+export type PrReviewFindings = {
+    specialists_run?: string[];
+    inline?: PrReviewFinding[];
+    off_diff?: PrReviewFinding[];
+    offDiff?: PrReviewFinding[];
+    patchPolicy?: unknown;
+};
+export type PrVortexReview = {
+    schema: "mergestorm.pr_review/v1";
+    id: string;
+    owner: string;
+    repo: string;
+    pr_number: number;
+    status: string;
+    raw_status?: string;
+    phase: string | null;
+    verdict: string | null;
+    summary?: string | null;
+    head_sha: string | null;
+    review_count: number;
+    skip_reason: string | null;
+    reviewed_at: string | null;
+    finding_count: number;
+    findings: PrReviewFindings | null;
+    patch_policy: unknown | null;
+};
+/**
+ * Bearer-writable settings keys, mirroring the `/api/v1/settings` allowlist.
+ * The connected flags are read-only there and deliberately absent here.
+ */
+export { SETTINGS_WRITABLE_KEYS };
+export type { SettingsWritableKey };
+export type SettingsPatch = Partial<Record<SettingsWritableKey, boolean>>;
+/** GET and PATCH `/api/v1/settings` both answer with this shape. */
+export type SettingsResponse = Record<SettingsWritableKey, boolean> & {
+    cyclone_connected: boolean;
+    github_connected: boolean;
+};
+/**
+ * Fetch Bearer /api/v1/settings; null on 404/network/timeouts so panels can
+ * degrade (same contract as {@link getMe}), while 401 still surfaces.
+ */
+export declare function getSettings(cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<SettingsResponse | null>;
+/**
+ * PATCH Bearer /api/v1/settings and return the stored result. Rejections
+ * (unknown key, cyclone_not_connected, …) surface the API's own `message`
+ * so the CLI never invents a reason.
+ */
+export declare function patchSettings(patch: SettingsPatch, cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<SettingsResponse>;
 /** Fetch /api/v1/me; returns null on 404/network so callers can degrade. */
 export declare function getMe(cfg?: Config, opts?: {
     timeoutMs?: number;
 }): Promise<MeResponse | null>;
-export declare function listJobs(limit?: number, cfg?: Config): Promise<JobListItem[]>;
+export declare function listJobs(limit?: number, cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<JobListItem[]>;
 /** Fetch one review job (Bearer GET /api/v1/reviews/:id). */
 export declare function getReview(jobId: string, cfg?: Config, opts?: {
     signal?: AbortSignal;
+    timeoutMs?: number;
 }): Promise<unknown>;
+/** Fetch the latest Vortex pass for one GitHub PR. */
+export declare function getPrVortexReview(owner: string, repo: string, prNumber: number, cfg?: Config, opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<PrVortexReview>;
 /** List stacks (Bearer GET /api/v1/stacks). */
 export declare function listStacks(cfg?: Config, opts?: {
     timeoutMs?: number;
 }): Promise<StackDto[]>;
+/** Fetch one owned stack with enriched GitHub checks and agent state. */
+export declare function getEnrichedStack(stackId: string, cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<StackDto | null>;
+/**
+ * Per-stack automation policy. Auto land is a boolean; the review / patch
+ * overrides are tri-state (`null` clears back to the account flag). Absent
+ * keys are left untouched.
+ */
+export type StackPolicyPatch = {
+    autoEnqueueWhenReady?: boolean;
+    autoReviewOverride?: boolean | null;
+    autoPatchOverride?: boolean | null;
+};
+/** Drop undefined keys so the wire body only carries what was requested. */
+export declare function stackPolicyBody(policy: StackPolicyPatch | undefined): StackPolicyPatch;
 /** 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>;
+export declare function adoptStack(owner: string, repo: string, prNumber: number, cfg?: Config, policy?: StackPolicyPatch): 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;
 }>;
+/** Arm or disarm Auto land on one owned stack. */
+export declare function setStackAutoLand(stackId: string, enabled: boolean, cfg?: Config): Promise<unknown>;
+/**
+ * Patch any subset of one owned stack's automation policy
+ * (Bearer PATCH /api/v1/stacks/:id). `null` clears an override.
+ */
+export declare function setStackPolicy(stackId: string, policy: StackPolicyPatch, cfg?: Config): Promise<unknown>;
 /** 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). */
 export declare function landNextStack(stackId: string, cfg?: Config, opts?: {
     prNumber?: number;
 }): Promise<unknown>;
-/** Toggle auto-promote when green (Bearer PATCH /api/v1/stacks/:id). */
-export declare function setStackAutoPromote(stackId: string, autoPromoteWhenGreen: boolean, cfg?: Config): Promise<unknown>;
+/** List the authenticated user's live merge-queue entries. */
+export declare function listMergeQueueEntries(cfg?: Config): Promise<MergeQueueEntryDto[]>;
+/** Enqueue a stack for verified landing. */
+export declare function enqueueStack(stackId: string, cfg?: Config): Promise<unknown>;
+/** Cancel a live merge-queue entry by entry id. */
+export declare function cancelMergeQueueEntry(entryId: string, cfg?: Config): Promise<unknown>;
 /** Recently reviewed branches/threads (Bearer GET /api/v1/threads). */
 export declare function listThreads(limit?: number, cfg?: Config): Promise<ThreadListItem[]>;

package/dist/api.js

@@ -1,4 +1,5 @@
 import { apiBase, loadConfig, resolveApiKey } from "./config.js";
+import { BEARER_SETTINGS_KEYS as SETTINGS_WRITABLE_KEYS, } from "./automation-catalog.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;
@@ -154,6 +155,63 @@ export async function devicePost(base, route, json, opts = {}) {
     }
     return { status: res.status, body: parsed };
 }
+/**
+ * Bearer-writable settings keys, mirroring the `/api/v1/settings` allowlist.
+ * The connected flags are read-only there and deliberately absent here.
+ */
+export { SETTINGS_WRITABLE_KEYS };
+/**
+ * Fetch Bearer /api/v1/settings; null on 404/network/timeouts so panels can
+ * degrade (same contract as {@link getMe}), while 401 still surfaces.
+ */
+export async function getSettings(cfg, opts) {
+    const resolved = cfg ?? (await loadConfig());
+    try {
+        const { status, body } = await apiFetch(resolved, "/api/v1/settings", {
+            timeoutMs: opts?.timeoutMs,
+        });
+        if (status !== 200)
+            return null;
+        return body;
+    }
+    catch (err) {
+        if (err instanceof CommandError) {
+            if (err.code === "api_timeout")
+                return null;
+            throw err;
+        }
+        return null;
+    }
+}
+/**
+ * PATCH Bearer /api/v1/settings and return the stored result. Rejections
+ * (unknown key, cyclone_not_connected, …) surface the API's own `message`
+ * so the CLI never invents a reason.
+ */
+export async function patchSettings(patch, cfg, opts) {
+    const resolved = cfg ?? (await loadConfig());
+    if (Object.keys(patch).length === 0) {
+        throw new CommandError("No settings to update.", 2, "usage");
+    }
+    const { status, body, retryAfterSeconds } = await apiFetch(resolved, "/api/v1/settings", {
+        method: "PATCH",
+        json: patch,
+        timeoutMs: opts?.timeoutMs,
+    });
+    if (status === 404) {
+        throw new CommandError("Settings API is not available on this server yet. Deploy the API update or use the dashboard.");
+    }
+    if (status === 429) {
+        throw new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds });
+    }
+    if (status !== 200) {
+        const message = body?.message;
+        throw new CommandError(typeof message === "string" && message.trim()
+            ? message
+            : `Failed to update settings (HTTP ${status}): ${JSON.stringify(body)}`);
+    }
+    return body;
+}
 /** Fetch /api/v1/me; returns null on 404/network so callers can degrade. */
 export async function getMe(cfg, opts) {
     const resolved = cfg ?? (await loadConfig());
@@ -178,10 +236,12 @@ export async function getMe(cfg, opts) {
         return null;
     }
 }
-export async function listJobs(limit = 10, cfg) {
+export async function listJobs(limit = 10, cfg, opts) {
     const resolved = cfg ?? (await loadConfig());
     const capped = Math.min(Math.max(limit, 1), 50);
-    const { status, body } = await apiFetch(resolved, `/api/v1/reviews?limit=${capped}`);
+    const { status, body } = await apiFetch(resolved, `/api/v1/reviews?limit=${capped}`, {
+        timeoutMs: opts?.timeoutMs,
+    });
     if (status === 404) {
         throw new CommandError("Job list is not available on this server yet. Update the API or use the dashboard.");
     }
@@ -198,7 +258,7 @@ export async function getReview(jobId, cfg, opts) {
     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 });
+    const { status, body, retryAfterSeconds } = await apiFetch(resolved, `/api/v1/reviews/${encodeURIComponent(id)}`, { signal: opts?.signal, timeoutMs: opts?.timeoutMs });
     if (status === 404) {
         throw new CommandError(`Review not found: ${id}`);
     }
@@ -210,27 +270,97 @@ export async function getReview(jobId, cfg, opts) {
     }
     return body;
 }
+/** Fetch the latest Vortex pass for one GitHub PR. */
+export async function getPrVortexReview(owner, repo, prNumber, cfg, opts) {
+    const resolved = cfg ?? (await loadConfig());
+    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");
+    }
+    const query = new URLSearchParams({
+        owner: cleanOwner,
+        repo: cleanRepo,
+        pr_number: String(prNumber),
+    });
+    const { status, body, retryAfterSeconds } = await apiFetch(resolved, `/api/v1/stacks/pr-review?${query.toString()}`, { signal: opts?.signal, timeoutMs: opts?.timeoutMs });
+    if (status === 404) {
+        throw new CommandError(`Vortex review not found: ${cleanOwner}/${cleanRepo}#${prNumber}`, REVIEW_EXIT.failed, "not_found");
+    }
+    if (status === 429) {
+        throw new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds });
+    }
+    if (status !== 200) {
+        throw new CommandError(`Failed to get PR review (HTTP ${status}): ${JSON.stringify(body)}`, REVIEW_EXIT.failed, "review_failed");
+    }
+    return body;
+}
 /** List stacks (Bearer GET /api/v1/stacks). */
 export async function listStacks(cfg, opts) {
     const resolved = cfg ?? (await loadConfig());
-    const { status, body } = await apiFetch(resolved, "/api/v1/stacks", {
+    const { status, body, retryAfterSeconds } = 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.");
     }
+    if (status === 429) {
+        throw new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds });
+    }
     if (status !== 200) {
         throw new CommandError(`Failed to list stacks (HTTP ${status}): ${JSON.stringify(body)}`);
     }
     const stacks = body.stacks;
     return Array.isArray(stacks) ? stacks : [];
 }
+/** Fetch one owned stack with enriched GitHub checks and agent state. */
+export async function getEnrichedStack(stackId, cfg, opts) {
+    const resolved = cfg ?? (await loadConfig());
+    const id = stackId.trim();
+    if (!id) {
+        throw new CommandError("stack_id is required", 2, "usage");
+    }
+    const { status, body, retryAfterSeconds } = await apiFetch(resolved, `/api/v1/stacks/enrich?stackId=${encodeURIComponent(id)}`, { timeoutMs: opts?.timeoutMs });
+    if (status === 404) {
+        throw new CommandError("Stack enrichment is not available on this server yet. Deploy the API update or use the dashboard.");
+    }
+    if (status === 429) {
+        throw new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds });
+    }
+    if (status !== 200) {
+        throw new CommandError(`Failed to get stack status (HTTP ${status}): ${JSON.stringify(body)}`);
+    }
+    const stacks = body.stacks;
+    if (!Array.isArray(stacks)) {
+        throw new CommandError(`Failed to get stack status (HTTP 200): ${JSON.stringify(body)}`);
+    }
+    return stacks.find((stack) => stack?.id === id) ?? null;
+}
+/** Drop undefined keys so the wire body only carries what was requested. */
+export function stackPolicyBody(policy) {
+    const body = {};
+    if (typeof policy?.autoEnqueueWhenReady === "boolean") {
+        body.autoEnqueueWhenReady = policy.autoEnqueueWhenReady;
+    }
+    if (policy?.autoReviewOverride !== undefined) {
+        body.autoReviewOverride = policy.autoReviewOverride;
+    }
+    if (policy?.autoPatchOverride !== undefined) {
+        body.autoPatchOverride = policy.autoPatchOverride;
+    }
+    return body;
+}
 /** Adopt an open PR chain (Bearer POST /api/v1/stacks/adopt). */
-export async function adoptStack(owner, repo, prNumber, cfg) {
+export async function adoptStack(owner, repo, prNumber, cfg, policy) {
     const resolved = cfg ?? (await loadConfig());
     const { status, body } = await apiFetch(resolved, "/api/v1/stacks/adopt", {
         method: "POST",
-        json: { owner, repo, prNumber },
+        json: {
+            owner,
+            repo,
+            prNumber,
+            ...stackPolicyBody(policy),
+        },
     });
     if (status === 404) {
         throw new CommandError("Stacks API is not available on this server yet. Deploy the API update or use the dashboard.");
@@ -272,6 +402,21 @@ async function stackMutation(stackId, pathSuffix, method, json, failLabel, cfg)
     }
     return body;
 }
+/** Arm or disarm Auto land on one owned stack. */
+export async function setStackAutoLand(stackId, enabled, cfg) {
+    return setStackPolicy(stackId, { autoEnqueueWhenReady: enabled }, cfg);
+}
+/**
+ * Patch any subset of one owned stack's automation policy
+ * (Bearer PATCH /api/v1/stacks/:id). `null` clears an override.
+ */
+export async function setStackPolicy(stackId, policy, cfg) {
+    const json = stackPolicyBody(policy);
+    if (Object.keys(json).length === 0) {
+        throw new CommandError("setStackPolicy needs at least one policy key");
+    }
+    return stackMutation(stackId, "", "PATCH", json, "Failed to set stack policy", cfg);
+}
 /** Restack descendants (Bearer POST /api/v1/stacks/:id/restack). */
 export async function restackStack(stackId, cfg) {
     return stackMutation(stackId, "/restack", "POST", {}, "Failed to restack", cfg);
@@ -283,9 +428,50 @@ export async function landNextStack(stackId, cfg, opts) {
         : {};
     return stackMutation(stackId, "/land-next", "POST", json, "Failed to land next", cfg);
 }
-/** Toggle auto-promote when green (Bearer PATCH /api/v1/stacks/:id). */
-export async function setStackAutoPromote(stackId, autoPromoteWhenGreen, cfg) {
-    return stackMutation(stackId, "", "PATCH", { autoPromoteWhenGreen }, "Failed to update auto-promote", cfg);
+/** List the authenticated user's live merge-queue entries. */
+export async function listMergeQueueEntries(cfg) {
+    const resolved = cfg ?? (await loadConfig());
+    const { status, body } = await apiFetch(resolved, "/api/v1/stacks/queue");
+    if (status === 404) {
+        throw new CommandError("Merge queue API is not available on this server yet. Deploy the API update or use the dashboard.");
+    }
+    if (status !== 200) {
+        throw new CommandError(`Failed to list merge queue (HTTP ${status}): ${JSON.stringify(body)}`);
+    }
+    const entries = body.entries;
+    if (!Array.isArray(entries)) {
+        throw new CommandError(`Failed to list merge queue (HTTP 200): ${JSON.stringify(body)}`);
+    }
+    return entries;
+}
+async function queueMutation(route, failLabel, cfg) {
+    const resolved = cfg ?? (await loadConfig());
+    const { status, body } = await apiFetch(resolved, route, {
+        method: "POST",
+        json: {},
+    });
+    if (status === 404) {
+        const error = body?.error;
+        if (error === "stack_not_found") {
+            throw new CommandError("Stack not found");
+        }
+        if (error === "entry_not_found") {
+            throw new CommandError("Merge queue entry not found");
+        }
+        throw new CommandError("Merge queue API is not available on this server yet. Deploy the API update or use the dashboard.");
+    }
+    if (status < 200 || status >= 300) {
+        throw new CommandError(`${failLabel} (HTTP ${status}): ${JSON.stringify(body)}`);
+    }
+    return body;
+}
+/** Enqueue a stack for verified landing. */
+export async function enqueueStack(stackId, cfg) {
+    return queueMutation(`/api/v1/stacks/${encodeURIComponent(stackId)}/enqueue`, "Failed to add stack to merge queue", cfg);
+}
+/** Cancel a live merge-queue entry by entry id. */
+export async function cancelMergeQueueEntry(entryId, cfg) {
+    return queueMutation(`/api/v1/stacks/queue/${encodeURIComponent(entryId)}/cancel`, "Failed to remove merge queue entry", cfg);
 }
 /** Recently reviewed branches/threads (Bearer GET /api/v1/threads). */
 export async function listThreads(limit = 20, cfg) {

package/dist/automation-catalog.d.ts

@@ -0,0 +1,37 @@
+export declare const BEARER_SETTINGS: readonly [{
+    readonly key: "auto_review_enabled";
+    readonly flag: "--auto-review";
+    readonly label: "Auto review";
+}, {
+    readonly key: "auto_patch_enabled";
+    readonly flag: "--auto-patch";
+    readonly label: "Auto patch";
+}, {
+    readonly key: "vortex_show_thinking_traces";
+    readonly flag: "--vortex-thinking";
+    readonly label: "Vortex thinking traces";
+}, {
+    readonly key: "repo_overview_enabled";
+    readonly flag: "--repo-overview";
+    readonly label: "Repo overview";
+}, {
+    readonly key: "review_unit_land_prs_enabled";
+    readonly flag: "--review-unit-land";
+    readonly label: "Review Unit land PRs";
+}, {
+    readonly key: "cyclone_review_unit_land_prs_enabled";
+    readonly flag: "--cyclone-review-unit-land";
+    readonly label: "Cyclone Review Unit land PRs";
+}, {
+    readonly key: "vortex_seam_specialist_enabled";
+    readonly flag: "--vortex-seam";
+    readonly label: "Vortex seam specialist";
+}, {
+    readonly key: "auto_land_default";
+    readonly flag: "--auto-land";
+    readonly label: "Auto land (new stacks)";
+}];
+export type BearerSettingsKey = (typeof BEARER_SETTINGS)[number]["key"];
+export declare const BEARER_SETTINGS_KEYS: readonly BearerSettingsKey[];
+export declare const BEARER_SETTINGS_FLAGS: Record<string, BearerSettingsKey>;
+export declare const BEARER_SETTINGS_LABELS: Record<BearerSettingsKey, string>;

package/dist/automation-catalog.js

@@ -0,0 +1,13 @@
+export const BEARER_SETTINGS = [
+    { key: "auto_review_enabled", flag: "--auto-review", label: "Auto review" },
+    { key: "auto_patch_enabled", flag: "--auto-patch", label: "Auto patch" },
+    { key: "vortex_show_thinking_traces", flag: "--vortex-thinking", label: "Vortex thinking traces" },
+    { key: "repo_overview_enabled", flag: "--repo-overview", label: "Repo overview" },
+    { key: "review_unit_land_prs_enabled", flag: "--review-unit-land", label: "Review Unit land PRs" },
+    { key: "cyclone_review_unit_land_prs_enabled", flag: "--cyclone-review-unit-land", label: "Cyclone Review Unit land PRs" },
+    { key: "vortex_seam_specialist_enabled", flag: "--vortex-seam", label: "Vortex seam specialist" },
+    { key: "auto_land_default", flag: "--auto-land", label: "Auto land (new stacks)" },
+];
+export const BEARER_SETTINGS_KEYS = BEARER_SETTINGS.map((r) => r.key);
+export const BEARER_SETTINGS_FLAGS = Object.fromEntries(BEARER_SETTINGS.map((r) => [r.flag, r.key]));
+export const BEARER_SETTINGS_LABELS = Object.fromEntries(BEARER_SETTINGS.map((r) => [r.key, r.label]));

package/dist/client/index.d.ts

@@ -1,5 +1,6 @@
 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 { BEARER_SETTINGS, BEARER_SETTINGS_FLAGS, BEARER_SETTINGS_KEYS, BEARER_SETTINGS_LABELS, type BearerSettingsKey, } from "../automation-catalog.js";
+export { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, SETTINGS_WRITABLE_KEYS, adoptStack, apiFetch, cancelMergeQueueEntry, devicePost, enqueueStack, ensureUpperPark, getEnrichedStack, getMe, getPrVortexReview, getReview, getSettings, landNextStack, listJobs, listMergeQueueEntries, listStacks, listThreads, parseRetryAfterSeconds, patchSettings, restackStack, setStackAutoLand, setStackPolicy, stackPolicyBody, type ApiFetchInit, type ApiFetchResult, type JobListItem, type MeResponse, type MergeQueueBounceDetail, type MergeQueueBounceKind, type MergeQueueEnqueuedBy, type MergeQueueEnqueuedVia, type MergeQueueEntryDto, type MergeQueueEntryState, type PrReviewFinding, type PrReviewFindings, type PrVortexReview, type SettingsPatch, type SettingsResponse, type SettingsWritableKey, type StackDto, type StackPolicyPatch, 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_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, PrReviewPollTimeoutError, ReviewPollTimeoutError, collectReviewInput, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollPrVortexReview, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, type PollReviewOptions, type PollPrVortexReviewOptions, 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

@@ -1,5 +1,6 @@
 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 { BEARER_SETTINGS, BEARER_SETTINGS_FLAGS, BEARER_SETTINGS_KEYS, BEARER_SETTINGS_LABELS, } from "../automation-catalog.js";
+export { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, SETTINGS_WRITABLE_KEYS, adoptStack, apiFetch, cancelMergeQueueEntry, devicePost, enqueueStack, ensureUpperPark, getEnrichedStack, getMe, getPrVortexReview, getReview, getSettings, landNextStack, listJobs, listMergeQueueEntries, listStacks, listThreads, parseRetryAfterSeconds, patchSettings, restackStack, setStackAutoLand, setStackPolicy, stackPolicyBody, } 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_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, PrReviewPollTimeoutError, ReviewPollTimeoutError, collectReviewInput, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollPrVortexReview, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, } from "../commands/review-client.js";
 export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, } from "../ui/job-envelope.js";

package/dist/commands/branches.d.ts

@@ -2,9 +2,13 @@ import { type ThreadListItem } from "../api.js";
 /** One-line label for a branch/thread row (also used by tests). */
 export declare function formatBranchRow(item: ThreadListItem): string;
 /** Interactive list of recently reviewed branches → open chain on select. */
-export declare function cmdBranches(args?: string[]): Promise<void>;
+export declare function cmdBranches(args?: string[], opts?: {
+    mode?: "oneshot" | "shell";
+}): Promise<void>;
 /**
  * Show the review-chain timeline for a branch/thread.
  * Defaults to `local/<current-git-branch>` when no slug is given.
  */
-export declare function cmdChain(args?: string[]): Promise<void>;
+export declare function cmdChain(args?: string[], opts?: {
+    mode?: "oneshot" | "shell";
+}): Promise<void>;