mergestorm 0.3.25 → 0.3.27

package/README.md

@@ -45,12 +45,12 @@ On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a comp
 
 ```
 ╭──────────────────────────────────────────────────────────────────────────────╮
-│ ▟██▛  mergestorm v0.3.25                                                     │
-│  ▜▙   ● 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.25: stack wait holds a PR while Cyclone or Vortex works   │
+│  ▀▀▀▀▀▀▀▀▀▀▘  mergestorm v0.3.27                                             │
+│ ▀▀▀▀▀▀▀▀▀     ● msk_live_… · maelstrom                                       │
+│  ▀▀▀▀▀▀       [████████░░░░░░░░░░░░░░░░░░░░░░] 25% used                      │
+│   ▝▀▀▀▀▀      local reviews + stacked PRs · mergestorm.ai                    │
+│     ▝▀▀▘      review a diff · usage for tabs · /help for all commands        │
+│       ▀       New: mg dismiss records an audited finding dismissal           │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
 ╭──────────────────────────────────────────────────────────────────────────────╮
@@ -96,8 +96,21 @@ mergestorm stack restack <stack-id>  Restack descendants
 mergestorm stack land <stack-id>     Land / promote (into review unit when present)
 mergestorm stack wait <stack-id> [--timeout <s>]  Wait for stack attention (default 45s, max 300s; 0 = one snapshot, no wait)
 mergestorm stack reset --force  Clear local authoring state (not branches/PRs)
+mergestorm dismiss <owner/repo>#<n> --head <sha> --review <id> --preview   List a Vortex review's finding ids and the seam gate
+mergestorm dismiss <owner/repo>#<n> --head <sha> --review <id> --finding <id> --reason <text>  Dismiss verified-wrong findings (`--all` for the whole review, `--evidence <url>`, `--json`)
 ```
 
+### Dismissing a finding
+
+Use `mergestorm dismiss` when a Vortex finding is wrong and you have checked it against the code. It is recorded server side with your GitHub login, the reason, the evidence URL, the scope and the time. Rules:
+
+- You need write access to the repository on GitHub, and the repository must be monitored by your Mergestorm account or the PR must be in one of your stacks.
+- `--head` must be the PR's live head and `--review` a Vortex review made at that head. A moved head, another review, or a finding id that is not in that review is refused, and nothing is written.
+- Retrying the same dismissal is safe; it reports the earlier record.
+- The seam gate clears only when every finding of that integration review is dismissed and the review is still the current seam verdict. CI, other reviews and Auto land policy still apply.
+- Vortex does not raise a dismissed finding again on the same diff (the same head, or a restack with an unchanged diff).
+- With `--json`, the result carries `gate` and, for a stack PR, `watch.next` (the next `stack_wait` call).
+
 `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. 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.

package/dist/api.d.ts

@@ -267,3 +267,62 @@ export declare function enqueueStack(stackId: string, cfg?: Config): Promise<unk
 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[]>;
+export type PrFindingDismissInput = {
+    owner: string;
+    repo: string;
+    prNumber: number;
+    headSha: string;
+    reviewId: number;
+    findingIds?: string[];
+    scope?: "findings" | "review";
+    reason?: string;
+    evidenceUrl?: string;
+    preview?: boolean;
+};
+export type PrDismissedFinding = {
+    finding_id: string;
+    finding_key: string;
+    path: string | null;
+    line: number | null;
+    title: string;
+};
+export type PrFindingDismissResult = {
+    status: "dismissed" | "preview";
+    owner: string;
+    repo: string;
+    pr_number: number;
+    head_sha: string;
+    review_id: number;
+    review_kind: "seam" | "core";
+    scope: "findings" | "review";
+    dismissed: PrDismissedFinding[];
+    already_dismissed: Array<PrDismissedFinding & {
+        actor_login: string;
+        dismissed_at: string;
+    }>;
+    remaining: PrDismissedFinding[];
+    all_dismissed: boolean;
+    gate: {
+        seam: {
+            state: string;
+            reviewed_sha: string | null;
+            review_id: number | null;
+            cleared: boolean;
+            blocking: boolean;
+        } | null;
+        other_gates: "unchanged";
+    };
+    stack_id: string | null;
+};
+export type PrFindingDismissOutcome = {
+    ok: true;
+    result: PrFindingDismissResult;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+    message: string;
+};
+export declare function dismissPrFindings(input: PrFindingDismissInput, cfg?: Config, opts?: {
+    signal?: AbortSignal;
+}): Promise<PrFindingDismissOutcome>;

package/dist/api.js

@@ -597,3 +597,43 @@ export async function listThreads(limit = 20, cfg) {
     const items = body.items;
     return Array.isArray(items) ? items : [];
 }
+export async function dismissPrFindings(input, cfg, opts) {
+    const resolved = cfg ?? (await loadConfig());
+    const json = {
+        owner: input.owner.trim(),
+        repo: input.repo.trim(),
+        pr_number: input.prNumber,
+        head_sha: input.headSha.trim(),
+        review_id: input.reviewId,
+        ...(input.scope ? { scope: input.scope } : {}),
+        ...(input.findingIds && input.findingIds.length > 0 ? { finding_ids: input.findingIds } : {}),
+        ...(input.reason !== undefined ? { reason: input.reason } : {}),
+        ...(input.evidenceUrl ? { evidence_url: input.evidenceUrl } : {}),
+        ...(input.preview ? { preview: true } : {}),
+    };
+    const { status, body, retryAfterSeconds } = await apiFetch(resolved, "/api/v1/stacks/pr-review/dismiss", {
+        method: "POST",
+        json,
+        signal: opts?.signal,
+    });
+    if (status === 429) {
+        throw new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", {
+            retryAfterSeconds,
+        });
+    }
+    if (status === 200)
+        return { ok: true, result: body };
+    const rejection = (body ?? {});
+    if (status === 404 && typeof rejection.error !== "string") {
+        throw new CommandError("Finding dismissal is not available on this server yet. Deploy the API update.", REVIEW_EXIT.failed, "not_found");
+    }
+    if (typeof rejection.error === "string") {
+        return {
+            ok: false,
+            status,
+            error: rejection.error,
+            message: typeof rejection.message === "string" ? rejection.message : rejection.error,
+        };
+    }
+    throw new CommandError(`Failed to dismiss findings (HTTP ${status}): ${JSON.stringify(body)}`, REVIEW_EXIT.failed, "review_failed");
+}

package/dist/client/index.d.ts

@@ -1,10 +1,11 @@
 export { DEFAULT_API, apiBase, clearConfig, configPath, keyDisplay, loadConfig, mergestormHome, resolveApiKey, saveConfig, type Config, } from "../config.js";
 export { BEARER_SETTINGS, BEARER_BOOLEAN_SETTINGS_KEYS, 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 { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, SETTINGS_WRITABLE_KEYS, adoptStack, apiFetch, cancelMergeQueueEntry, devicePost, dismissPrFindings, 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 PrDismissedFinding, type PrFindingDismissInput, type PrFindingDismissOutcome, type PrFindingDismissResult, 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, PrReviewPollTimeoutError, ReviewPollTimeoutError, collectReviewInput, formatReviewSubmitError, 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";
 export { discoverTrunk } from "../git-stack.js";
 export { BOUNCE_KIND_LABELS, deriveStackAgentsBusy, mergeQueueBounceLabel, type StackAgentsBusy } from "../stack-dto.js";
 export { STACK_WATCH_SCHEMA, STACK_WATCH_DEFAULT_TIMEOUT_MS, STACK_WATCH_BUSY_RECHECK_S, StackWatchError, StackWatchTimeoutError, pollStackWatch, type PollStackWatchOptions, type StackWatchCursor, type StackWatchEnvelope, } from "../stack-watch.js";
-export { stackBlockers, stackBlockersSummary, sameHead, layerAgents, layerAgentsBusy, type StackAgentBusy, type StackBlocker, type StackLayerAgents, } from "../stack-blockers.js";
+export { stackBlockers, stackBlockersSummary, sameHead, layerAgents, layerAgentsBusy, conflictLiveParent, stackRepair, agentsCannotClear, type StackAgentBusy, type StackBlocker, type StackBusyAgent, type StackHeldBlocker, type StackLandGatePending, type StackLayerAgents, type StackRepairHint, } from "../stack-blockers.js";
+export { STACK_WATCH_NOT_DONE_SENTENCE, stackTerminalReason, stackWatchNextArgs, stackWatchObligation, type StackWatchDoneReason, type StackWatchNext, type StackWatchNextArgs, type StackWatchObligation, type StackWatchObligationInput, type StackWatchReason, } from "../stack-watch-obligation.js";

package/dist/client/index.js

@@ -1,10 +1,11 @@
 export { DEFAULT_API, apiBase, clearConfig, configPath, keyDisplay, loadConfig, mergestormHome, resolveApiKey, saveConfig, } from "../config.js";
 export { BEARER_SETTINGS, BEARER_BOOLEAN_SETTINGS_KEYS, 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 { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, SETTINGS_WRITABLE_KEYS, adoptStack, apiFetch, cancelMergeQueueEntry, devicePost, dismissPrFindings, 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, PrReviewPollTimeoutError, ReviewPollTimeoutError, collectReviewInput, formatReviewSubmitError, isTransientReviewPollError, isTransientReviewPollStatus, loadReviewContext, pollPrVortexReview, pollReview, stretchedPollIntervalMs, submitReview, transientRetryWaitMs, } from "../commands/review-client.js";
 export { REVIEW_JOB_ENVELOPE_SCHEMA, toReviewJobEnvelope, } from "../ui/job-envelope.js";
 export { discoverTrunk } from "../git-stack.js";
 export { BOUNCE_KIND_LABELS, deriveStackAgentsBusy, mergeQueueBounceLabel } from "../stack-dto.js";
 export { STACK_WATCH_SCHEMA, STACK_WATCH_DEFAULT_TIMEOUT_MS, STACK_WATCH_BUSY_RECHECK_S, StackWatchError, StackWatchTimeoutError, pollStackWatch, } from "../stack-watch.js";
-export { stackBlockers, stackBlockersSummary, sameHead, layerAgents, layerAgentsBusy, } from "../stack-blockers.js";
+export { stackBlockers, stackBlockersSummary, sameHead, layerAgents, layerAgentsBusy, conflictLiveParent, stackRepair, agentsCannotClear, } from "../stack-blockers.js";
+export { STACK_WATCH_NOT_DONE_SENTENCE, stackTerminalReason, stackWatchNextArgs, stackWatchObligation, } from "../stack-watch-obligation.js";

package/dist/commands/dismiss.d.ts

@@ -0,0 +1,15 @@
+import { type PrFindingDismissInput, type PrFindingDismissOutcome, type PrFindingDismissResult } from "../api.js";
+import { type Config } from "../config.js";
+import { type StackWatchObligation } from "../stack-watch-obligation.js";
+export declare const DISMISS_USAGE: string;
+export type ParsedDismissArgs = PrFindingDismissInput & {
+    json: boolean;
+};
+export declare function parseDismissArgs(args: string[]): ParsedDismissArgs;
+export declare function dismissWatch(result: PrFindingDismissResult): StackWatchObligation | null;
+export declare function formatDismissResult(result: PrFindingDismissResult, watch: StackWatchObligation | null): string;
+export type DismissDeps = {
+    loadConfig?: () => Promise<Config>;
+    dismiss?: (input: PrFindingDismissInput, cfg: Config) => Promise<PrFindingDismissOutcome>;
+};
+export declare function cmdDismiss(args: string[], deps?: DismissDeps): Promise<void>;

package/dist/commands/dismiss.js

@@ -0,0 +1,145 @@
+import { dismissPrFindings, } from "../api.js";
+import { loadConfig } from "../config.js";
+import { CommandError, REVIEW_EXIT } from "../errors.js";
+import { stackWatchObligation } from "../stack-watch-obligation.js";
+import { parseAdoptTarget, withWatch } from "./stack.js";
+export const DISMISS_USAGE = [
+    "usage: mergestorm dismiss <owner/repo>#<n> --head <sha> --review <id>",
+    "         (--finding <id> [--finding <id>…] | --all) --reason <text> [--evidence <url>] [--json]",
+    "       mergestorm dismiss <owner/repo>#<n> --head <sha> --review <id> --preview [--json]",
+].join("\n");
+function usage(message) {
+    return new CommandError(message ? `${message}\n${DISMISS_USAGE}` : DISMISS_USAGE, REVIEW_EXIT.usage, "usage");
+}
+export function parseDismissArgs(args) {
+    const target = [];
+    const findingIds = [];
+    let headSha = "";
+    let reviewId;
+    let reason;
+    let evidenceUrl;
+    let all = false;
+    let preview = false;
+    let json = false;
+    const value = (flag, raw) => {
+        if (raw === undefined || raw.startsWith("--"))
+            throw usage(`${flag} needs a value`);
+        return raw;
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--head")
+            headSha = value(arg, args[++i]).trim().toLowerCase();
+        else if (arg === "--review") {
+            const raw = value(arg, args[++i]).trim();
+            if (!/^[1-9]\d*$/.test(raw) || !Number.isSafeInteger(Number(raw)))
+                throw usage("--review needs the numeric GitHub review id");
+            reviewId = Number(raw);
+        }
+        else if (arg === "--finding")
+            findingIds.push(...value(arg, args[++i]).split(",").map((id) => id.trim()).filter(Boolean));
+        else if (arg === "--all")
+            all = true;
+        else if (arg === "--reason")
+            reason = value(arg, args[++i]);
+        else if (arg === "--evidence")
+            evidenceUrl = value(arg, args[++i]).trim();
+        else if (arg === "--preview")
+            preview = true;
+        else if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("--"))
+            throw usage(`unknown flag ${arg}`);
+        else
+            target.push(arg);
+    }
+    let parsedTarget;
+    try {
+        parsedTarget = parseAdoptTarget(target);
+    }
+    catch {
+        throw usage("name the PR as <owner/repo>#<n>");
+    }
+    if (!/^[0-9a-f]{40}$/.test(headSha))
+        throw usage("--head needs the full 40-character PR head SHA");
+    if (reviewId === undefined)
+        throw usage("--review is required");
+    if (!preview) {
+        if (all && findingIds.length > 0)
+            throw usage("pass --finding or --all, not both");
+        if (!all && findingIds.length === 0)
+            throw usage("pass --finding <id> for each finding, or --all for the whole review");
+        if (!reason?.trim())
+            throw usage("--reason is required: say why the finding is wrong or not actionable");
+    }
+    return {
+        ...parsedTarget,
+        headSha,
+        reviewId,
+        findingIds: all ? [] : findingIds,
+        scope: all ? "review" : "findings",
+        ...(reason !== undefined ? { reason } : {}),
+        ...(evidenceUrl ? { evidenceUrl } : {}),
+        preview,
+        json,
+    };
+}
+export function dismissWatch(result) {
+    if (!result.stack_id)
+        return null;
+    return stackWatchObligation({ stackId: result.stack_id, terminal: null, unread: true, freshCursor: true });
+}
+function findingLine(finding) {
+    const where = finding.path ? `${finding.path}${finding.line ? `:${finding.line}` : ""}` : "review body";
+    return `  ${finding.finding_id}  ${where}  ${finding.title}`;
+}
+export function formatDismissResult(result, watch) {
+    const lines = [];
+    const pr = `${result.owner}/${result.repo}#${result.pr_number}`;
+    const kind = result.review_kind === "seam" ? "seam review" : "Vortex review";
+    if (result.status === "preview") {
+        lines.push(`${pr} ${kind} ${result.review_id} at ${result.head_sha.slice(0, 7)}: ${result.remaining.length} open finding(s)`);
+        lines.push(...result.remaining.map(findingLine));
+    }
+    else {
+        lines.push(`${pr} ${kind} ${result.review_id} at ${result.head_sha.slice(0, 7)}`);
+        if (result.dismissed.length)
+            lines.push("Dismissed:", ...result.dismissed.map(findingLine));
+        if (result.already_dismissed.length) {
+            lines.push("Already dismissed:", ...result.already_dismissed.map((f) => `${findingLine(f)}  (by @${f.actor_login})`));
+        }
+        if (result.remaining.length)
+            lines.push("Still open:", ...result.remaining.map(findingLine));
+    }
+    const seam = result.gate.seam;
+    if (seam) {
+        lines.push(seam.cleared
+            ? "Seam gate: cleared (approved at this head). CI, other reviews and Auto land policy still apply."
+            : seam.blocking
+                ? `Seam gate: still blocking (seam_state=${seam.state}).`
+                : `Seam gate: not blocking (seam_state=${seam.state}).`);
+    }
+    if (watch?.next)
+        lines.push(`Next: ${watch.next.command}`);
+    return lines.join("\n");
+}
+export async function cmdDismiss(args, deps = {}) {
+    const parsed = parseDismissArgs(args);
+    const cfg = await (deps.loadConfig ?? loadConfig)();
+    const { json, ...input } = parsed;
+    const outcome = await (deps.dismiss ?? ((i, c) => dismissPrFindings(i, c)))(input, cfg);
+    if (!outcome.ok) {
+        if (json) {
+            console.log(JSON.stringify({ error: { code: outcome.error, message: outcome.message } }, null, 2));
+            process.exitCode = REVIEW_EXIT.failed;
+            return;
+        }
+        throw new CommandError(`Dismissal refused (${outcome.error}): ${outcome.message}`, REVIEW_EXIT.failed, "review_failed");
+    }
+    const watch = dismissWatch(outcome.result);
+    if (json) {
+        console.log(JSON.stringify(withWatch(outcome.result, watch), null, 2));
+        return;
+    }
+    console.log(formatDismissResult(outcome.result, watch));
+}

package/dist/commands/registry.js

@@ -3,6 +3,7 @@ import { CommandError } from "../errors.js";
 import { cmdBranches, cmdChain } from "./branches.js";
 import { canBrowse, openTabsBrowser } from "./browse.js";
 import { cmdCredits } from "./credits.js";
+import { cmdDismiss } from "./dismiss.js";
 import { cmdJobs, cmdThread } from "./jobs.js";
 import { cmdLogin } from "./login.js";
 import { cmdLogout } from "./logout.js";
@@ -79,6 +80,21 @@ export const COMMAND_REGISTRY = [
             });
         },
     },
+    {
+        name: "dismiss",
+        summary: "Dismiss Vortex findings you verified are wrong (audited)",
+        usage: [
+            "mergestorm dismiss <owner/repo>#<n> --head <sha> --review <id> --preview",
+            "  Lists the review's findings (ids) and the seam gate; writes nothing",
+            "mergestorm dismiss <owner/repo>#<n> --head <sha> --review <id> --finding <id> --reason <text>",
+            "  [--finding <id>]… | --all (every finding of that review)  [--evidence <url>] [--json]",
+            "  Needs write access on GitHub; refuses a moved head, another review or an unknown id",
+            "  Clears the seam gate only when every finding of that seam review is dismissed",
+        ],
+        async run(args) {
+            await cmdDismiss(args);
+        },
+    },
     {
         name: "status",
         summary: "Job panel (id) or Status / Usage / Jobs tabs",
@@ -224,7 +240,7 @@ export const COMMAND_REGISTRY = [
             "mergestorm stack reset --force  Clear this repo's pre-submit authoring state",
             "mergestorm stack list [--json]  List registered stacks",
             "mergestorm stack status <stack-id> [--json]  Enriched stack status",
-            "mergestorm stack wait <stack-id> [--json] [--timeout <s>]  Wait for stack attention (default 45s, max 300s; 0 = one snapshot, no wait)",
+            "mergestorm stack wait <stack-id> [--json] [--timeout <s>]  Wait for stack attention (default 45s, max 300s; 0 = one snapshot, no wait). --json: one document on stdout; timeout notice on stderr, exit 5",
             "mergestorm stack set <stack-id> [--auto-land on|off] [--auto-review on|off|default] [--auto-patch on|off|default] [--json]  Per-stack policy",
             "mergestorm stack adopt <owner/repo>#<pr> [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off]  Import an open PR chain",
             "mergestorm stack restack <stack-id>   Restack stack descendants",

package/dist/commands/stack.d.ts

@@ -1,3 +1,5 @@
+import { type StackHeldBlocker, type StackRepairHint } from "../stack-blockers.js";
+import { type StackWatchObligation } from "../stack-watch-obligation.js";
 import { adoptStack, ensureUpperPark, findStackPull, getEnrichedStack, listStacks, openStackPull, setStackPolicy, type StackDto, type StackPolicyPatch } from "../api.js";
 import { loadConfig } from "../config.js";
 import { createPrs, findOpenPrNumber } from "../gh.js";
@@ -7,6 +9,12 @@ import { buildPrBodyFromCommit } from "../pr-body.js";
 import { gitTopLevel } from "../repo-identity.js";
 import { loadStackMeta, saveStackMeta } from "../stack-meta.js";
 import { pollStackWatch } from "../stack-watch.js";
+export declare function stackHeldLine(held: StackHeldBlocker | null | undefined): string[];
+export declare function stackRepairLine(repair: StackRepairHint | null | undefined): string[];
+export declare function stackWatchTextLines(watch: StackWatchObligation | null | undefined): string[];
+export declare function openStackWatch(stackId: string, opts?: {
+    unread?: boolean;
+}): StackWatchObligation;
 /** A registered stack layer that would become the parent of a new layer. */
 export type RegisteredParentHit = {
     stackId: string;
@@ -140,6 +148,7 @@ export type StackSetDeps = {
 };
 /** Human summary lines for a `stack set` write, one per flag. */
 export declare function stackSetSummary(parsed: StackSetArgs): string[];
+export declare function withWatch(body: unknown, watch: StackWatchObligation | null): unknown;
 export declare function cmdStackSet(args: string[], deps?: StackSetDeps): Promise<void>;
 export declare function cmdStack(args: string[], options?: {
     signal?: AbortSignal;

package/dist/commands/stack.js

@@ -1,4 +1,5 @@
-import { stackBlockersSummary } from "../stack-blockers.js";
+import { stackBlockers, stackBlockersSummary } from "../stack-blockers.js";
+import { STACK_WATCH_NOT_DONE_SENTENCE, stackTerminalReason, stackWatchObligation, } from "../stack-watch-obligation.js";
 import { adoptStack, ensureUpperPark, findStackPull, getEnrichedStack, landNextStack, listStacks, openStackPull, restackStack, setStackPolicy, } from "../api.js";
 import { loadConfig } from "../config.js";
 import { rateLimitedMessage, REVIEW_EXIT, CommandError } from "../errors.js";
@@ -15,6 +16,32 @@ import { runLineTabsBrowser } from "../ui/line-tabs.js";
 import { present } from "../ui/present.js";
 import { canBrowse } from "./browse.js";
 import { openHelpBrowser } from "./help.js";
+export function stackHeldLine(held) {
+    if (!held)
+        return [];
+    const agents = held.waitingOn.map((agent) => agent === "cyclone" ? "Cyclone" : "Vortex").join(" and ");
+    return [`Held: #${held.prNumber} ${held.blocker}. Plan the fix; act once ${agents} ${held.waitingOn.length > 1 ? "are" : "is"} idle and the watch returns attention.`];
+}
+export function stackRepairLine(repair) {
+    if (!repair)
+        return [];
+    const files = "files" in repair && repair.files.length ? ` (files: ${repair.files.join(", ")})` : "";
+    return [`Repair #${repair.prNumber} ${repair.kind}${files}: ${repair.steps}`];
+}
+export function stackWatchTextLines(watch) {
+    if (!watch)
+        return [];
+    if (watch.done)
+        return [watch.message];
+    const next = watch.next;
+    return [
+        ...(next ? [`Next: ${next.command} (MCP: stack_wait ${JSON.stringify(next.args)})`] : []),
+        STACK_WATCH_NOT_DONE_SENTENCE,
+    ];
+}
+export function openStackWatch(stackId, opts = {}) {
+    return stackWatchObligation({ stackId, terminal: null, unread: opts.unread, freshCursor: true });
+}
 const STACK_USAGE = `usage:
   mergestorm stack create [name] [--onto <branch>] [--trunk <branch>] [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--json]
   mergestorm stack submit [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--rest] [--json]
@@ -22,6 +49,8 @@ const STACK_USAGE = `usage:
   mergestorm stack list [--json]
   mergestorm stack status <stack-id> [--json]
   mergestorm stack wait <stack-id> [--json] [--timeout <s>]
+    --json writes exactly one JSON document to stdout. The timeout or error notice goes to stderr
+    (exit 5 on timeout), so do not merge the streams (2>&1) before parsing stdout.
   mergestorm stack set <stack-id> [--auto-land on|off] [--auto-review on|off|default] [--auto-patch on|off|default] [--json]
   mergestorm stack adopt <owner/repo>#<pr> [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--json]
   mergestorm stack restack <stack-id> [--json]
@@ -780,6 +809,7 @@ export async function cmdStackSubmit(args, deps = {}) {
             stackId: stackId ?? null,
             trunk: data.stack?.trunkBranch ?? meta.trunk,
             chain: data.chain ?? null,
+            watch: stackId ? openStackWatch(stackId) : null,
         }, null, 2));
         return;
     }
@@ -799,6 +829,8 @@ export async function cmdStackSubmit(args, deps = {}) {
         summary.push(ansi.dim("  Stack registration returned no stack ID"));
     }
     summary.push(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
+    if (stackId)
+        summary.push(...stackWatchTextLines(openStackWatch(stackId)).map((line) => `  ${line}`));
     await present("Stack", summary);
 }
 async function cmdStackReset(args) {
@@ -868,7 +900,11 @@ export async function cmdStackWait(args, deps = {}) {
             ...envelope,
             ...(retryAfterSeconds !== undefined ? { retry_after_seconds: retryAfterSeconds } : {}),
         }, null, 2)
-        : `Stack ${envelope.stackId} · ${envelope.status}${stackBlockersSummary(envelope.blocker && envelope.prNumber != null ? { prNumber: envelope.prNumber, blocker: envelope.blocker } : null, envelope.issues, envelope.busy)}${envelope.assessment === "unavailable" ? " · assessment unavailable" : ""}`);
+        : [
+            `Stack ${envelope.stackId} · ${envelope.status}${stackBlockersSummary(envelope.blocker && envelope.prNumber != null ? { prNumber: envelope.prNumber, blocker: envelope.blocker } : null, envelope.issues, envelope.busy, envelope.landGatePending ?? null, envelope.actAfter ?? null)}${envelope.assessment === "unavailable" ? " · assessment unavailable" : ""}`,
+            ...stackRepairLine(envelope.repair),
+            ...stackWatchTextLines(envelope.watch),
+        ].join("\n"));
     try {
         print(await (deps.pollStackWatch ?? pollStackWatch)(cfg, stackId, {
             timeoutMs: timeoutS * 1000,
@@ -892,6 +928,7 @@ export async function cmdStackWait(args, deps = {}) {
 }
 export async function cmdStackStatus(args, deps = {}) {
     const usage = "usage: mergestorm stack status <stack-id> [--json]";
+    const asJson = args.includes("--json");
     const positional = args.filter((arg) => arg !== "--json");
     if (positional.length !== 1)
         throw new CommandError(usage, 2, "usage");
@@ -899,10 +936,25 @@ export async function cmdStackStatus(args, deps = {}) {
     const cfg = await (deps.loadConfig ?? loadConfig)();
     const stack = await (deps.getEnrichedStack ?? getEnrichedStack)(stackId, cfg);
     if (!stack) {
+        const watch = stackWatchObligation({ stackId, terminal: "not_found" });
+        if (asJson) {
+            console.log(JSON.stringify({ error: { code: "not_found", stack_id: stackId }, watch }, null, 2));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(watch.message);
         throw new CommandError(`Stack not found or not owned by the current user: ${stackId}`, 1, "not_found");
     }
-    if (args.includes("--json")) {
-        console.log(JSON.stringify(stack, null, 2));
+    const { attention, held, currentCandidate, repair } = stackBlockers(stack);
+    const watch = stackWatchObligation({
+        stackId: stack.id,
+        terminal: stackTerminalReason(stack),
+        cursor: { enrolledHeadSha: currentCandidate?.headSha ?? null },
+        attention: attention ? { prNumber: attention.prNumber, blocker: attention.blocker } : null,
+        freshCursor: true,
+    });
+    if (asJson) {
+        console.log(JSON.stringify({ ...stack, held, repair, watch }, null, 2));
         return;
     }
     const lines = formatStackHuman(stack, false);
@@ -915,6 +967,7 @@ export async function cmdStackStatus(args, deps = {}) {
             (layer.cycloneStatus ? `  Cyclone: ${layer.cycloneStatus}` : "") +
             (layer.tempestStatus ? `  Tempest: ${layer.tempestStatus}` : ""));
     }
+    lines.push(...[...stackHeldLine(held), ...stackRepairLine(repair), ...stackWatchTextLines(watch)].map((line) => `  ${line}`));
     await present("Stack status", lines);
 }
 /** Human summary lines for a `stack set` write, one per flag. */
@@ -932,6 +985,11 @@ export function stackSetSummary(parsed) {
     }
     return lines;
 }
+export function withWatch(body, watch) {
+    if (!watch || typeof body !== "object" || body === null || Array.isArray(body))
+        return body;
+    return { ...body, watch };
+}
 export async function cmdStackSet(args, deps = {}) {
     const parsed = parseStackSetArgs(args);
     const cfg = await (deps.loadConfig ?? loadConfig)();
@@ -940,18 +998,26 @@ export async function cmdStackSet(args, deps = {}) {
         ...(parsed.autoReview !== undefined ? { autoReviewOverride: parsed.autoReview } : {}),
         ...(parsed.autoPatch !== undefined ? { autoPatchOverride: parsed.autoPatch } : {}),
     }, cfg);
+    const watch = openStackWatch(parsed.stackId, { unread: true });
     if (parsed.asJson) {
-        console.log(JSON.stringify(body, null, 2));
+        console.log(JSON.stringify(withWatch(body, watch), null, 2));
         return;
     }
-    await present("Stack", stackSetSummary(parsed).map((line) => ansi.brightGreen(`  ${line} for ${parsed.stackId}`)));
+    await present("Stack", [
+        ...stackSetSummary(parsed).map((line) => ansi.brightGreen(`  ${line} for ${parsed.stackId}`)),
+        ...stackWatchTextLines(watch).map((line) => `  ${line}`),
+    ]);
 }
 async function cmdStackAdopt(args) {
     const { owner, repo, prNumber, autoLand, autoReview, autoPatch, asJson } = parseStackAdoptArgs(args);
     const cfg = await loadConfig();
     const body = await adoptStack(owner, repo, prNumber, cfg, openPolicyPatch({ autoLand, autoReview, autoPatch }));
+    const adoptedId = typeof body === "object" && body !== null
+        ? body.stack?.id
+        : undefined;
+    const watch = typeof adoptedId === "string" && adoptedId ? openStackWatch(adoptedId, { unread: true }) : null;
     if (asJson) {
-        console.log(JSON.stringify(body, null, 2));
+        console.log(JSON.stringify(withWatch(body, watch), null, 2));
         return;
     }
     if (typeof body !== "object" || body === null) {
@@ -969,6 +1035,7 @@ async function cmdStackAdopt(args) {
         imported.push(ansi.dim(`  trunk: ${stack.trunkBranch}`));
     }
     imported.push(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
+    imported.push(...stackWatchTextLines(watch).map((line) => `  ${line}`));
     await present("Stack", imported);
 }
 async function cmdStackRestack(args) {

package/dist/shell.js

@@ -79,7 +79,7 @@ export async function runShell() {
                     commands: COMMANDS,
                     ...(banner
                         ? {
-                            header: (columns, variant) => banner.rows(columns, variant),
+                            header: (columns, variant, frame) => banner.rows(columns, variant, frame),
                         }
                         : {}),
                 });