mergestorm 0.3.62 → 0.3.63

package/README.md

@@ -45,12 +45,12 @@ On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a comp
 
 ```
 ╭──────────────────────────────────────────────────────────────────────────────╮
-│  ▀▀▀▀▀▀▀▀▀▀▘  mergestorm v0.3.62                                             │
+│  ▀▀▀▀▀▀▀▀▀▀▘  mergestorm v0.3.63                                             │
 │ ▀▀▀▀▀▀▀▀▀     ● msk_live_… · maelstrom                                       │
 │  ▀▀▀▀▀▀       [████████░░░░░░░░░░░░░░░░░░░░░░] 25% used                      │
 │   ▝▀▀▀▀▀      local reviews + stacked PRs · mergestorm.ai                    │
 │     ▝▀▀▘      review a diff · usage for tabs · /help for all commands        │
-│       ▀       New in v0.3.62: Watch wakes for a blocker on any layer         │
+│       ▀       New in v0.3.63: Stack create starts a new stack unless --extend│
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
 ╭──────────────────────────────────────────────────────────────────────────────╮
@@ -93,7 +93,7 @@ mergestorm thread <slug>        Jobs in a review thread
 mergestorm issue create --title <t>  Open a GitHub issue through Mergestorm, no `gh` (`--body`, `--body-file`, `--label`, `--repo`)
 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`, `--server-side`)
-mergestorm stack publish        Publish the current branch through Mergestorm with no GitHub credentials (`--status` to read it)
+mergestorm stack publish        Publish the current branch through Mergestorm with no GitHub credentials (`--base <branch> --extend` to stack, `--status` to read it)
 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
@@ -138,9 +138,14 @@ Use `mergestorm dismiss` when a Vortex finding is wrong and you have checked it
 
 `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.
+`stack create` always starts a new single PR from trunk unless you pass **`--extend`**, even when the worktree is still on an earlier PR's branch: it checks out the new branch from `origin/<trunk>` (or local trunk; from `HEAD` when trunk is checked out). It 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.
 
-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`.
+Both paths are one command:
+
+- New stack from trunk: `mg stack create <name>` (from any branch), then `mg stack submit`.
+- Grow a stack: `mg stack create <name> --extend` on the branch to stack onto (or `--onto <branch> --extend`), then `mg stack submit --extend` when the parent is a layer of a registered stack. `mg stack publish --base <branch> --extend` does the same for publish.
+
+`--onto` or `--base` with a branch other than trunk and no `--extend` is refused, so nothing is added to a stack by accident. Every create, submit and publish prints which one it made: a new single PR onto trunk, or a layer stacked on its parent.
 
 `stack submit` walks the **active** local stack: `git push -u origin` each layer, opens a PR with `gh` (`--base` = parent or trunk; adopt then moves the bottom of a 2+ PR stack onto `mg-stack-<n>` — leave it there; 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 is always your local `git` credentials. PRs open as you when `gh` is installed and `gh api user` succeeds; otherwise `stack submit` asks the Mergestorm API (`POST /api/v1/stacks/pulls`) to open them as the Mergestorm Surge App on your behalf, after checking your GitHub account has write access, and assigns you. Stacks, the merge queue and Auto land run through Surge, and Cyclone is the auto-patch App. Without Surge, submit stops before pushing and prints the server's message, which names the App to install and links its install page. `mg settings` prints a `Stacks, merge queue, Auto land` line when the server reports whether that App is ready.
 

package/dist/api.d.ts

@@ -142,6 +142,14 @@ export type PrVortexReview = {
     reviewed_at: string | null;
     finding_count: number;
     findings: PrReviewFindings | null;
+    dismissed_findings?: Array<{
+        path: string;
+        line: number;
+        title: string;
+        severity: string;
+        finding_key: string;
+        github_comment_id: number | null;
+    }>;
     patch_policy: unknown | null;
     /**
      * MS-01: True when the returned row is a resting completion but a newer
@@ -458,7 +466,12 @@ export type PrFindingDismissResult = {
         other_gates: "unchanged";
     };
     stack_id: string | null;
+    threads?: Array<{
+        finding_id: string;
+        state: "resolved" | "already_resolved" | "not_found" | "failed";
+    }>;
 };
+export declare function dismissThreadsLine(result: Pick<PrFindingDismissResult, "threads">): string | null;
 export type PrFindingDismissOutcome = {
     ok: true;
     result: PrFindingDismissResult;

package/dist/api.js

@@ -773,6 +773,19 @@ export async function listThreads(limit = 20, cfg) {
     const items = body.items;
     return Array.isArray(items) ? items : [];
 }
+export function dismissThreadsLine(result) {
+    const threads = result.threads ?? [];
+    if (threads.length === 0)
+        return null;
+    const closed = threads.filter((thread) => thread.state === "resolved" || thread.state === "already_resolved").length;
+    const failed = threads.filter((thread) => thread.state === "failed").map((thread) => thread.finding_id);
+    const missing = threads.filter((thread) => thread.state === "not_found").map((thread) => thread.finding_id);
+    return [
+        `GitHub threads: ${closed} of ${threads.length} resolved.`,
+        ...(failed.length ? [`Could not resolve ${failed.join(", ")}; run the same dismissal again to retry.`] : []),
+        ...(missing.length ? [`No thread found for ${missing.join(", ")}.`] : []),
+    ].join(" ");
+}
 export async function dismissPrFindings(input, cfg, opts) {
     const resolved = cfg ?? (await loadConfig());
     const json = {

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
 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, dismissPrFindings, enqueueStack, ensureUpperPark, getEnrichedStack, getMe, getPrVortexReview, getReview, getSettings, listRepoSettings, patchRepoSettings, REPO_SETTINGS_KEYS, getStackPublication, landNextStack, listJobs, listMergeQueueEntries, listStacks, listThreads, openStackIssue, parseRetryAfterSeconds, patchSettings, restackStack, setStackPolicy, stackPolicyBody, submitStackPublication, 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 RepoSettings, type RepoSettingsKey, type RepoSettingsPatch, type SettingsResponse, type StackDto, type StackPolicyPatch, type StackPublication, type StackPublicationRequest, type StackPublicationStatus, type ThreadDetail, type ThreadListItem, } from "../api.js";
+export { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, SETTINGS_WRITABLE_KEYS, adoptStack, apiFetch, cancelMergeQueueEntry, devicePost, dismissPrFindings, dismissThreadsLine, enqueueStack, ensureUpperPark, getEnrichedStack, getMe, getPrVortexReview, getReview, getSettings, listRepoSettings, patchRepoSettings, REPO_SETTINGS_KEYS, getStackPublication, landNextStack, listJobs, listMergeQueueEntries, listStacks, listThreads, openStackIssue, parseRetryAfterSeconds, patchSettings, restackStack, setStackPolicy, stackPolicyBody, submitStackPublication, 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 RepoSettings, type RepoSettingsKey, type RepoSettingsPatch, type SettingsResponse, type StackDto, type StackPolicyPatch, type StackPublication, type StackPublicationRequest, type StackPublicationStatus, 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, noPrReviewYetMessage, 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";

package/dist/client/index.js

@@ -1,6 +1,6 @@
 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, dismissPrFindings, enqueueStack, ensureUpperPark, getEnrichedStack, getMe, getPrVortexReview, getReview, getSettings, listRepoSettings, patchRepoSettings, REPO_SETTINGS_KEYS, getStackPublication, landNextStack, listJobs, listMergeQueueEntries, listStacks, listThreads, openStackIssue, parseRetryAfterSeconds, patchSettings, restackStack, setStackPolicy, stackPolicyBody, submitStackPublication, } from "../api.js";
+export { API_TIMEOUT_PREFIX, DEFAULT_API_TIMEOUT_MS, SETTINGS_WRITABLE_KEYS, adoptStack, apiFetch, cancelMergeQueueEntry, devicePost, dismissPrFindings, dismissThreadsLine, enqueueStack, ensureUpperPark, getEnrichedStack, getMe, getPrVortexReview, getReview, getSettings, listRepoSettings, patchRepoSettings, REPO_SETTINGS_KEYS, getStackPublication, landNextStack, listJobs, listMergeQueueEntries, listStacks, listThreads, openStackIssue, parseRetryAfterSeconds, patchSettings, restackStack, setStackPolicy, stackPolicyBody, submitStackPublication, } 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, noPrReviewYetMessage, 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";

package/dist/commands/dismiss.js

@@ -1,4 +1,4 @@
-import { dismissPrFindings, } from "../api.js";
+import { dismissPrFindings, dismissThreadsLine, } from "../api.js";
 import { loadConfig } from "../config.js";
 import { CommandError, REVIEW_EXIT } from "../errors.js";
 import { stackWatchObligation } from "../stack-watch-obligation.js";
@@ -110,6 +110,9 @@ export function formatDismissResult(result, watch) {
         }
         if (result.remaining.length)
             lines.push("Still open:", ...result.remaining.map(findingLine));
+        const threads = dismissThreadsLine(result);
+        if (threads)
+            lines.push(threads);
     }
     const seam = result.gate.seam;
     if (seam) {

package/dist/commands/stack.d.ts

@@ -4,7 +4,7 @@ import { adoptStack, ensureUpperPark, findStackPull, getEnrichedStack, getStackP
 import { loadConfig } from "../config.js";
 import { createPrs, findOpenPrNumber } from "../gh.js";
 import { parseGithubOriginRepo } from "../git.js";
-import { branchExists, commitsAheadOf, createBranchFromHead, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, fetchRemoteBranch, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty } from "../git-stack.js";
+import { branchExists, commitsAheadOf, createBranchFrom, createBranchFromHead, trunkStartRef, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, fetchRemoteBranch, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty } from "../git-stack.js";
 import { buildPrBodyFromCommit } from "../pr-body.js";
 import { publishBranchServerSide, type WorkingBranchDeps } from "../server-publish.js";
 import { gitTopLevel } from "../repo-identity.js";
@@ -33,6 +33,11 @@ export declare function findRegisteredParent(stacks: StackDto[], parentBranch: s
  * Local unsubmitted parents are fine; only API-listed layers trip this.
  */
 export declare function assertMayParentOntoRegistered(parentBranch: string, stacks: StackDto[], extend: boolean, verb: "create" | "submit", owner?: string, repo?: string): RegisteredParentHit | null;
+export declare function stackShapeLine(input: {
+    layers: number;
+    base: string;
+    extendedStack: boolean;
+}): string;
 export declare function requireStackId(raw: string | undefined, usage: string): string;
 /** Parse `owner/repo#12` or `owner/repo 12`. */
 export declare function parseAdoptTarget(args: string[]): {
@@ -110,6 +115,8 @@ export type StackCreateDeps = {
     currentBranch?: typeof currentBranch;
     branchExists?: typeof branchExists;
     createBranchFromHead?: typeof createBranchFromHead;
+    createBranchFrom?: typeof createBranchFrom;
+    trunkStartRef?: typeof trunkStartRef;
     deleteBranch?: typeof deleteBranch;
     discoverTrunk?: typeof discoverTrunk;
     defaultLayerBranchName?: typeof defaultLayerBranchName;
@@ -156,6 +163,7 @@ export declare function parseStackPublishArgs(args: string[]): {
     title?: string;
     replaceHead?: string;
     autoLand?: boolean;
+    extend: boolean;
     status: boolean;
     asJson: boolean;
 };

package/dist/commands/stack.js

@@ -5,9 +5,9 @@ import { loadConfig } from "../config.js";
 import { rateLimitedMessage, REVIEW_EXIT, CommandError } from "../errors.js";
 import { createPrs, findOpenPrNumber, ghReady, githubApiFromEnv, } from "../gh.js";
 import { parseGithubOriginRepo } from "../git.js";
-import { branchExists, commitsAheadOf, createBranchFromHead, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, fetchRemoteBranch, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty, } from "../git-stack.js";
+import { branchExists, commitsAheadOf, createBranchFrom, createBranchFromHead, trunkStartRef, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, fetchRemoteBranch, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty, } from "../git-stack.js";
 import { buildPrBodyFromCommit } from "../pr-body.js";
-import { publishBranchServerSide, publishWorkingBranch, workingBranchPublication, } from "../server-publish.js";
+import { publishBranchServerSide, assertExplicitStacking, publishWorkingBranch, workingBranchPublication, } from "../server-publish.js";
 import { gitTopLevel } from "../repo-identity.js";
 import { activeLayers, appendLayer, emptyStackMeta, loadStackMeta, removeActiveStack, resetStackMeta, saveStackMeta, selectStackForCreate, setActivePolicy, } from "../stack-meta.js";
 import { pollStackWatch, StackWatchError, StackWatchTimeoutError, } from "../stack-watch.js";
@@ -52,7 +52,7 @@ export function openStackWatch(stackId, opts = {}) {
 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] [--auto-resolve-conflicts on|off] [--auto-fix-ci on|off] [--json]
   mergestorm stack submit [--extend] [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--auto-resolve-conflicts on|off] [--auto-fix-ci on|off] [--rest] [--server-side] [--json]
-  mergestorm stack publish [--branch <branch>] [--base <branch>] [--title <title>] [--replace-head <sha>] [--auto-land on|off] [--status] [--json]
+  mergestorm stack publish [--branch <branch>] [--base <branch>] [--extend] [--title <title>] [--replace-head <sha>] [--auto-land on|off] [--status] [--json]
   mergestorm stack reset --force
   mergestorm stack list [--json]
   mergestorm stack status <stack-id> [--json]
@@ -95,10 +95,13 @@ const STACK_USAGE = `usage:
   you name that head with --replace-head. stack publish --status reads how far
   a branch got (absent, pushed, opened, registered) without changing anything;
   after a lost response or a failure, run the same command again to resume.
-  Parenting onto a branch that already belongs to a registered (submitted)
-  stack requires --extend on create and submit — otherwise mg starts a new
-  stack from trunk. stack land promotes into the review unit when one exists;
-  otherwise lands the bottom open PR (unit-less stacks).`;
+  stack create starts a new single PR from trunk, even on another PR's
+  branch. --extend stacks it on the checked-out branch (or --onto <branch>)
+  instead; --onto or publish --base a branch other than trunk without
+  --extend is refused. A layer on a registered stack also needs --extend on
+  submit. create, submit and publish say which one they made. stack land
+  promotes into the review unit when one exists; otherwise lands the bottom
+  open PR (unit-less stacks).`;
 /** Cap the registered-stack guard's API probe so it cannot stall local authoring. */
 const STACK_GUARD_TIMEOUT_MS = 8_000;
 async function listRegisteredStacksRetryingOnce(list, cfg) {
@@ -152,6 +155,13 @@ export function assertMayParentOntoRegistered(parentBranch, stacks, extend, verb
         `• New independent stack: check out trunk and pass \`--onto <trunk>\` (e.g. \`mg stack create --onto main\`).\n` +
         `• Intentionally grow that stack: pass \`--extend\` on \`stack ${verb}\`.`, 1, "registered_parent");
 }
+export function stackShapeLine(input) {
+    if (input.extendedStack)
+        return `  Added ${input.layers === 1 ? "1 layer" : `${input.layers} layers`} to an existing stack (--extend).`;
+    if (input.layers === 1)
+        return `  A new single PR onto ${input.base}.`;
+    return `  A new stack of ${input.layers} layers onto ${input.base}.`;
+}
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 export function requireStackId(raw, usage) {
     const id = raw?.trim() ?? "";
@@ -525,6 +535,8 @@ export async function cmdStackCreate(args, deps = {}) {
     const currentBranchFn = deps.currentBranch ?? currentBranch;
     const branchExistsFn = deps.branchExists ?? branchExists;
     const createBranchFromHeadFn = deps.createBranchFromHead ?? createBranchFromHead;
+    const createBranchFromFn = deps.createBranchFrom ?? createBranchFrom;
+    const trunkStartRefFn = deps.trunkStartRef ?? trunkStartRef;
     const deleteBranchFn = deps.deleteBranch ?? deleteBranch;
     const discoverTrunkFn = deps.discoverTrunk ?? discoverTrunk;
     const defaultLayerBranchNameFn = deps.defaultLayerBranchName ?? defaultLayerBranchName;
@@ -542,17 +554,6 @@ export async function cmdStackCreate(args, deps = {}) {
     if (worktreeDirtyFn(cwd)) {
         throw new CommandError("Working tree is dirty. Commit or stash changes before `stack create`.");
     }
-    const parentBranch = onto?.trim() || currentBranchFn(cwd);
-    if (!parentBranch) {
-        throw new CommandError("Detached HEAD. Check out a branch (or pass --onto <branch>) before `stack create`.");
-    }
-    if (!branchExistsFn(parentBranch, cwd)) {
-        throw new CommandError(`Parent branch not found: ${parentBranch}`);
-    }
-    const branch = defaultLayerBranchNameFn(name);
-    if (branchExistsFn(branch, cwd)) {
-        throw new CommandError(`Branch already exists: ${branch}`);
-    }
     let meta = await loadStackMetaFn(cwd);
     const trunk = trunkFlag?.trim() || meta?.trunk || discoverTrunkFn(cwd);
     if (!meta) {
@@ -561,8 +562,34 @@ export async function cmdStackCreate(args, deps = {}) {
     else if (trunkFlag?.trim() && meta.trunk !== trunk) {
         throw new CommandError(`Stack trunk is ${meta.trunk}; refusing --trunk ${trunk}. Run \`mg stack reset --force\` to discard local pre-submit state.`);
     }
-    // --trunk only sets metadata; parent defaults to current branch. Call that out
-    // when someone passes --trunk while sitting on a different branch without --onto.
+    const checkedOut = currentBranchFn(cwd);
+    if (extend && !onto?.trim() && !checkedOut) {
+        throw new CommandError("Detached HEAD. Check out a branch (or pass --onto <branch>) to stack with --extend.");
+    }
+    const parentBranch = onto?.trim() || (extend && checkedOut ? checkedOut : trunk);
+    assertExplicitStacking({
+        parent: parentBranch,
+        trunk,
+        extend,
+        stackCommand: `\`mg stack create ${name ?? "<name>"} --onto ${parentBranch} --extend\``,
+        trunkCommand: `\`mg stack create ${name ?? "<name>"}\``,
+    });
+    let startRef = null;
+    if (parentBranch === trunk && checkedOut !== trunk) {
+        startRef = trunkStartRefFn(trunk, cwd);
+        if (!startRef)
+            throw new CommandError(`Trunk branch not found: ${trunk}`);
+    }
+    else if (!branchExistsFn(parentBranch, cwd)) {
+        throw new CommandError(`Parent branch not found: ${parentBranch}`);
+    }
+    else if (parentBranch !== checkedOut) {
+        startRef = parentBranch;
+    }
+    const branch = defaultLayerBranchNameFn(name);
+    if (branchExistsFn(branch, cwd)) {
+        throw new CommandError(`Branch already exists: ${branch}`);
+    }
     if (trunkFlag?.trim() && !onto?.trim() && parentBranch !== trunk) {
         console.error(ansi.dim(`  note: --trunk ${trunk} does not change the parent; new layer parents onto \`${parentBranch}\`. ` +
             `Pass \`--onto ${trunk}\` for a fresh stack from trunk.`));
@@ -606,7 +633,10 @@ export async function cmdStackCreate(args, deps = {}) {
         throw new CommandError(err instanceof Error ? err.message : String(err));
     }
     try {
-        createBranchFromHeadFn(branch, cwd);
+        if (startRef)
+            createBranchFromFn(branch, startRef, cwd);
+        else
+            createBranchFromHeadFn(branch, cwd);
     }
     catch (err) {
         throw new CommandError(err instanceof Error ? err.message : String(err));
@@ -637,7 +667,9 @@ export async function cmdStackCreate(args, deps = {}) {
         return;
     }
     const created = [
-        ansi.brightGreen(`  Created ${branch} (onto ${parentBranch})`),
+        ansi.brightGreen(parentBranch === meta.trunk
+            ? `  Created ${branch}: a new single PR onto ${parentBranch}${startRef ? ` (branched from ${startRef})` : ""}`
+            : `  Created ${branch}: a layer stacked on ${parentBranch} (--extend)`),
     ];
     if (registeredHit) {
         created.push(ansi.dim(`  extending registered stack ${registeredHit.stackId}` +
@@ -847,6 +879,7 @@ export async function cmdStackSubmit(args, deps = {}) {
             return;
         }
         const lines = published.map((row) => ansi.brightGreen(`  #${row.prNumber}  ${row.branch} → ${row.base}  (${row.created ? "opened" : "exists"}, head ${row.head.slice(0, 12)})`));
+        lines.push(ansi.brightGreen(stackShapeLine({ layers: layers.length, base: plans[0]?.githubBase ?? meta.trunk, extendedStack: registeredHits > 0 })));
         if (publishedStackId)
             lines.push(ansi.brightGreen(`  Registered stack ${publishedStackId}`));
         lines.push(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
@@ -987,6 +1020,7 @@ export async function cmdStackSubmit(args, deps = {}) {
         const verb = row.created ? "opened" : "exists";
         summary.push(ansi.brightGreen(`  #${row.prNumber}  ${row.branch} → ${row.base}  (${verb})`));
     }
+    summary.push(ansi.brightGreen(stackShapeLine({ layers: layers.length, base: plans[0]?.githubBase ?? meta.trunk, extendedStack: registeredHits > 0 })));
     const adoptedTrunk = data.stack?.trunkBranch;
     if (adoptedTrunk?.startsWith("mg-stack-")) {
         summary.push(ansi.dim(`  Bottom base is now ${adoptedTrunk} (Mergestorm-owned trunk). Leave it.`));
@@ -1003,8 +1037,8 @@ export async function cmdStackSubmit(args, deps = {}) {
     await present("Stack", summary);
 }
 export function parseStackPublishArgs(args) {
-    const usage = "usage: mergestorm stack publish [--branch <branch>] [--base <branch>] [--title <title>] [--replace-head <sha>] [--auto-land on|off] [--status] [--json]";
-    const out = { status: false, asJson: false };
+    const usage = "usage: mergestorm stack publish [--branch <branch>] [--base <branch>] [--extend] [--title <title>] [--replace-head <sha>] [--auto-land on|off] [--status] [--json]";
+    const out = { extend: false, status: false, asJson: false };
     const valued = {
         "--branch": "branch",
         "--base": "base",
@@ -1021,6 +1055,10 @@ export function parseStackPublishArgs(args) {
             out.status = true;
             continue;
         }
+        if (a === "--extend") {
+            out.extend = true;
+            continue;
+        }
         if (a === "--auto-land") {
             out.autoLand = parseOnOff(args[++i], "--auto-land", "stack publish");
             continue;
@@ -1066,6 +1104,7 @@ export async function cmdStackPublish(args, deps = {}) {
         ...(parsed.title ? { title: parsed.title } : {}),
         ...(typeof parsed.autoLand === "boolean" ? { autoLand: parsed.autoLand } : {}),
         ...(parsed.replaceHead ? { replaceHead: parsed.replaceHead } : {}),
+        extend: parsed.extend,
     }, publishDeps);
     const watch = openStackWatch(result.stack.id);
     if (parsed.asJson) {
@@ -1076,6 +1115,7 @@ export async function cmdStackPublish(args, deps = {}) {
     await present("Stack", [
         ansi.brightGreen(`  ${result.branch} ${moved} at ${result.head.sha.slice(0, 12)} (tree ${result.head.tree.slice(0, 12)})`),
         ansi.brightGreen(`  #${result.pr.number}  ${result.branch} → ${result.baseBranch}  (${result.pr.created ? "opened" : "exists"})  ${result.pr.url}`),
+        ansi.brightGreen(result.stacked ? `  A layer stacked on ${result.baseBranch}.` : `  A single PR onto ${result.baseBranch}.`),
         ansi.brightGreen(`  Registered stack ${result.stack.id}`),
         ...stackWatchTextLines(watch).map((line) => `  ${line}`),
     ]);

package/dist/config.d.ts

@@ -2,6 +2,7 @@ export declare const DEFAULT_API = "https://api.mergestorm.ai";
 export type Config = {
     apiKey?: string;
     apiBase?: string;
+    ignoreEnv?: boolean;
 };
 export declare function mergestormHome(env?: NodeJS.ProcessEnv): string;
 export declare function configPath(): string;

package/dist/config.js

@@ -30,9 +30,12 @@ export async function clearConfig() {
     await rm(configPath(), { force: true });
 }
 export function apiBase(cfg) {
-    return (process.env.MERGESTORM_API_URL?.trim() || cfg.apiBase || DEFAULT_API).replace(/\/$/, "");
+    const fromEnv = cfg.ignoreEnv ? undefined : process.env.MERGESTORM_API_URL?.trim();
+    return (fromEnv || cfg.apiBase || DEFAULT_API).replace(/\/$/, "");
 }
 export function resolveApiKey(cfg) {
+    if (cfg.ignoreEnv)
+        return cfg.apiKey;
     return process.env.MERGESTORM_API_KEY?.trim() || cfg.apiKey;
 }
 /** Short display form of a stored key (prefix only). */

package/dist/errors.d.ts

@@ -2,7 +2,7 @@
  * Stable machine codes for CommandError control flow.
  * UX copy in `message` may change freely; match on `code`, never on message text.
  */
-export type CommandErrorCode = "auth_invalid" | "api_timeout" | "not_a_repo" | "not_found" | "missing_api_key" | "registered_parent" | "usage" | "review_quota" | "review_failed" | "review_timeout" | "rate_limited" | "cyclone_not_installed" | "pr_merged" | "pr_closed" | "not_stacked" | "draft" | "reserved_branch" | "supabase_unconfigured" | "cyclone_not_connected" | "cyclone_permission_missing" | "busy" | "adopt_failed" | "github_unreadable" | "stack_attention" | "head_changed" | "base_changed" | "tree_mismatch" | "protected_branch" | "payload_too_large" | "unsupported_publication" | "publication_failed" | "unknown_label";
+export type CommandErrorCode = "auth_invalid" | "api_timeout" | "not_a_repo" | "not_found" | "missing_api_key" | "registered_parent" | "implicit_stack" | "usage" | "review_quota" | "review_failed" | "review_timeout" | "rate_limited" | "cyclone_not_installed" | "pr_merged" | "pr_closed" | "not_stacked" | "draft" | "reserved_branch" | "supabase_unconfigured" | "cyclone_not_connected" | "cyclone_permission_missing" | "busy" | "adopt_failed" | "github_unreadable" | "stack_attention" | "head_changed" | "base_changed" | "tree_mismatch" | "protected_branch" | "payload_too_large" | "unsupported_publication" | "publication_failed" | "unknown_label";
 /** Stable one-shot exit codes for machine callers of `mergestorm review`. */
 export declare const REVIEW_EXIT: {
     readonly success: 0;

package/dist/git-stack.d.ts

@@ -15,6 +15,8 @@ export declare function discoverTrunk(cwd?: string): string;
 export declare function branchExists(name: string, cwd?: string): boolean;
 export declare function deleteBranch(name: string, cwd?: string): void;
 export declare function createBranchFromHead(name: string, cwd?: string): void;
+export declare function createBranchFrom(name: string, start: string, cwd?: string): void;
+export declare function trunkStartRef(trunk: string, cwd?: string): string | null;
 /** Slugify a free-form name into a safe branch segment. */
 export declare function slugifyBranchName(raw: string): string;
 export declare function defaultLayerBranchName(explicit?: string): string;

package/dist/git-stack.js

@@ -78,6 +78,21 @@ export function deleteBranch(name, cwd = process.cwd()) {
 export function createBranchFromHead(name, cwd = process.cwd()) {
     git(["checkout", "-b", name], cwd);
 }
+export function createBranchFrom(name, start, cwd = process.cwd()) {
+    git(["checkout", "-b", name, start], cwd);
+}
+export function trunkStartRef(trunk, cwd = process.cwd()) {
+    for (const ref of [`refs/remotes/origin/${trunk}`, `refs/heads/${trunk}`]) {
+        try {
+            git(["rev-parse", "--verify", "--quiet", ref], cwd);
+            return ref === `refs/heads/${trunk}` ? trunk : `origin/${trunk}`;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
 /** Slugify a free-form name into a safe branch segment. */
 export function slugifyBranchName(raw) {
     const s = raw

package/dist/server-publish.d.ts

@@ -1,5 +1,6 @@
 import { getStackPublication, submitStackPublication, type StackPublication, type StackPublicationChange, type StackPublicationCommit, type StackPublicationIdentity, type StackPublicationStatus } from "./api.js";
 import { loadConfig, type Config } from "./config.js";
+import { discoverTrunk } from "./git-stack.js";
 export declare const SERVER_PUBLISH_MAX_COMMITS = 20;
 export declare const SERVER_PUBLISH_MAX_CHANGES = 500;
 export declare const SERVER_PUBLISH_MAX_FILE_BYTES: number;
@@ -39,6 +40,7 @@ export type ServerPublishDeps = {
     read?: GitRead;
     getStackPublication?: typeof getStackPublication;
     submitStackPublication?: typeof submitStackPublication;
+    assertBase?: (base: string) => void;
 };
 export type ServerPublishResult = StackPublication & {
     baseBranch: string;
@@ -54,17 +56,28 @@ export type WorkingBranchInput = {
     body?: string;
     autoLand?: boolean;
     replaceHead?: string;
+    extend?: boolean;
     cfg?: Config;
 };
 export type WorkingBranchDeps = ServerPublishDeps & {
     publishBranchServerSide?: typeof publishBranchServerSide;
     loadConfig?: typeof loadConfig;
+    discoverTrunk?: typeof discoverTrunk;
 };
+export declare function assertExplicitStacking(input: {
+    parent: string;
+    trunk: string;
+    extend: boolean;
+    stackCommand: string;
+    trunkCommand: string;
+}): void;
 export declare function workingBranchTarget(input: WorkingBranchInput): {
     cwd: string;
     owner: string;
     repo: string;
     branch: string;
 };
-export declare function publishWorkingBranch(input: WorkingBranchInput, deps?: WorkingBranchDeps): Promise<ServerPublishResult>;
+export declare function publishWorkingBranch(input: WorkingBranchInput, deps?: WorkingBranchDeps): Promise<ServerPublishResult & {
+    stacked: boolean;
+}>;
 export declare function workingBranchPublication(input: WorkingBranchInput, deps?: Pick<WorkingBranchDeps, "getStackPublication" | "loadConfig">): Promise<StackPublicationStatus>;

package/dist/server-publish.js

@@ -180,6 +180,7 @@ export async function publishBranchServerSide(input, deps = {}) {
         throw new CommandError(`Branch missing locally: ${branch}`);
     const remote = await status(cfg, { owner, repo, branch });
     const baseBranch = remote.pr?.base ?? input.baseBranch;
+    deps.assertBase?.(baseBranch);
     const localBase = input.localBaseRef ??
         (resolves(read, `refs/remotes/origin/${input.baseBranch}`, cwd) ? `refs/remotes/origin/${input.baseBranch}` : input.baseBranch);
     if (!resolves(read, localBase, cwd))
@@ -229,6 +230,13 @@ export async function publishBranchServerSide(input, deps = {}) {
     }
     return { ...publication, baseBranch };
 }
+export function assertExplicitStacking(input) {
+    if (input.extend || input.parent === input.trunk)
+        return;
+    throw new CommandError(`\`${input.parent}\` is not trunk (\`${input.trunk}\`), and stacking onto it needs --extend.\n` +
+        `• Stack onto \`${input.parent}\`: ${input.stackCommand}\n` +
+        `• New stack from \`${input.trunk}\`: ${input.trunkCommand}`, 1, "implicit_stack");
+}
 export function workingBranchTarget(input) {
     const cwd = input.cwd ?? process.cwd();
     const origin = input.owner && input.repo ? { owner: input.owner, repo: input.repo } : parseGithubOriginRepo(cwd);
@@ -242,17 +250,36 @@ export function workingBranchTarget(input) {
 }
 export async function publishWorkingBranch(input, deps = {}) {
     const { cwd, owner, repo, branch } = workingBranchTarget(input);
-    let baseBranch = input.base;
+    const { publishBranchServerSide: publish = publishBranchServerSide, loadConfig: load = loadConfig, discoverTrunk: findTrunk = discoverTrunk, ...publishDeps } = deps;
+    let trunk = null;
+    let trunkError = null;
+    try {
+        trunk = findTrunk(cwd);
+    }
+    catch (err) {
+        trunkError = err;
+    }
+    const trunkMessage = trunkError instanceof Error ? trunkError.message : String(trunkError);
+    const baseBranch = input.base ?? trunk;
     if (!baseBranch) {
-        try {
-            baseBranch = discoverTrunk(cwd);
+        throw new CommandError(`${trunkMessage} Name the base branch.`);
+    }
+    const assertBase = (parent) => {
+        if (trunk) {
+            assertExplicitStacking({
+                parent,
+                trunk,
+                extend: input.extend === true,
+                stackCommand: `\`mg stack publish --base ${parent} --extend\` (MCP stack_publish: extend true)`,
+                trunkCommand: "`mg stack publish` with no --base (MCP stack_publish: no base)",
+            });
         }
-        catch (err) {
-            throw new CommandError(`${err instanceof Error ? err.message : String(err)} Name the base branch.`);
+        else if (input.extend !== true) {
+            throw new CommandError(`${trunkMessage} \`${parent}\` cannot be verified as trunk, so stacking onto it needs --extend.`, 1, "implicit_stack");
         }
-    }
-    const { publishBranchServerSide: publish = publishBranchServerSide, loadConfig: load = loadConfig, ...publishDeps } = deps;
-    return publish({
+    };
+    assertBase(baseBranch);
+    const result = await publish({
         cfg: input.cfg ?? (await load()),
         cwd,
         owner,
@@ -263,7 +290,8 @@ export async function publishWorkingBranch(input, deps = {}) {
         body: input.body ?? buildPrBodyFromCommit(tipCommitMessage(branch, cwd)),
         ...(typeof input.autoLand === "boolean" ? { autoLand: input.autoLand } : {}),
         ...(input.replaceHead ? { replaceHead: input.replaceHead } : {}),
-    }, publishDeps);
+    }, { ...publishDeps, assertBase });
+    return { ...result, stacked: !trunk || result.baseBranch !== trunk };
 }
 export async function workingBranchPublication(input, deps = {}) {
     const { owner, repo, branch } = workingBranchTarget(input);

package/dist/stack-blockers.d.ts

@@ -170,6 +170,8 @@ export declare const SEAM_REVIEW_STUCK = "Seam review stuck in reviewing, no rev
 export declare const SEAM_REREVIEW_NOT_RUNNING = "Seam re-review pending, no review running";
 export declare const SEAM_VERDICT_STALE = "Seam verdict is for an older head, no review running";
 export declare const VORTEX_FINDINGS_NEED_PERSON = "Vortex findings need a person";
+export declare const CYCLONE_NOT_RUN_ATTENTION_MS: number;
+export declare const CYCLONE_NOT_RUN_REASON = "not_run";
 export declare function cycloneStatusWords(layer: Pick<StackLayerDto, "cycloneStatus" | "cycloneHandoff" | "headSha">): string | null;
 export declare function autoResolveActive(stack: StackDto, layer: StackLayerDto): boolean;
 export declare function autoFixCiActive(stack: StackDto, layer: StackLayerDto): boolean;
@@ -216,7 +218,7 @@ export declare function restackFailedRepairSteps(branch: string, liveParent: str
     detail?: string | null;
 }): string;
 export declare function agentsCannotClear(reason: StackBlockerReason, stack?: StackDto, layer?: StackLayerDto): boolean;
-export declare function stackRepair(stack: StackDto, attention: ClassifiedStackBlocker | null, layer: StackLayerDto | undefined, bounce: MergeQueueEntryDto | undefined, queueWait?: MergeQueueWait | null): StackRepairHint | null;
+export declare function stackRepair(stack: StackDto, attention: ClassifiedStackBlocker | null, layer: StackLayerDto | undefined, bounce: MergeQueueEntryDto | undefined, queueWait?: MergeQueueWait | null, nowMs?: number): StackRepairHint | null;
 export declare const LAND_PR_MISSING_PREFIX = "No open land PR for ";
 /** Pair-gate attention plus live hard blocks on every other open layer. */
 export declare function stackBlockers(stack: StackDto, entries?: MergeQueueEntryDto[], cursor?: Pick<StackWatchCursor, "bounceId" | "afterFinishedAt">, nowMs?: number): {

package/dist/stack-blockers.js

@@ -72,10 +72,26 @@ function vortexFindingsRestAtHead(layer) {
 function vortexChangesRequestedAtHead(layer) {
     return vortexFindingsRestAtHead(layer) && layer.reviewStatus === "changes_requested";
 }
-function cycloneHandoffAtHead(stack, layer) {
+export const CYCLONE_NOT_RUN_ATTENTION_MS = 30 * 60_000;
+export const CYCLONE_NOT_RUN_REASON = "not_run";
+function cycloneNotRunAtHead(layer, nowMs) {
+    const review = layer.vortexReview;
+    if (layer.cycloneFindingsTakenAtHead !== false || layer.vortexStatus !== "findings")
+        return false;
+    if (review?.status !== "done" || !sameHead(review.head_sha, layer.headSha))
+        return false;
+    const settledMs = Date.parse(review.settled_at ?? "");
+    return Number.isFinite(settledMs) && nowMs - settledMs >= CYCLONE_NOT_RUN_ATTENTION_MS;
+}
+function cycloneHandoffAtHead(stack, layer, nowMs) {
     if (sameHead(layer.cycloneHandoff?.headSha, layer.headSha))
         return layer.cycloneHandoff.reason;
-    return stack.cyclonePatchOff ?? (stack.autoPatchOverride === false ? "auto_patch_off" : null);
+    if (layer.cycloneStatus === "failed")
+        return "failed";
+    const off = stack.cyclonePatchOff ?? (stack.autoPatchOverride === false ? "auto_patch_off" : null);
+    if (off)
+        return off;
+    return cycloneNotRunAtHead(layer, nowMs) ? CYCLONE_NOT_RUN_REASON : null;
 }
 const CYCLONE_HANDOFF_WORDS = {
     failed: "Cyclone's patch failed, so it pushed nothing",
@@ -93,6 +109,11 @@ const CYCLONE_HANDOFF_WORDS = {
     unsupported_language: "the findings are in a language Cyclone does not patch",
     policy_owner_changed: "the stack's owner changed while the patch was queued",
     patch_job_lost: "Cyclone's patch job was lost before it finished",
+    pr_state_unavailable: "Cyclone could not read the PR's state, so it pushed nothing",
+    left_for_human: "Cyclone did not patch these findings and pushed nothing",
+    hold: "the review told Cyclone to hold, so it did not patch these findings",
+    vortex_patch_cap: "Cyclone already patched this PR as many times as it may",
+    [CYCLONE_NOT_RUN_REASON]: `Cyclone has not run on this head in the ${CYCLONE_NOT_RUN_ATTENTION_MS / 60_000} minutes since Vortex posted these findings, and nothing is patching it`,
     conflict_needs_person: "Cyclone could not resolve the conflict and left it for a person",
     conflict_unresolved: "Cyclone's conflict resolution failed",
     auto_resolve_daily_cap: "Cyclone already resolved conflicts on this PR twice today, its daily cap",
@@ -179,6 +200,10 @@ const CYCLONE_HELD_FINDINGS_REASONS = [
     "pr_state_unavailable",
     "vortex_patch_cap",
     "patch_job_lost",
+    "unsupported_language",
+    "credits_exhausted",
+    "no_billing",
+    "policy_owner_changed",
 ];
 function vortexImportantFindingsHeldAtHead(layer) {
     return vortexFindingsRestAtHead(layer) && layer.reviewStatus === "reviewed" &&
@@ -189,13 +214,13 @@ function seamApprovedAtHead(stack, layer) {
     const member = (stack.unit?.members ?? []).find((entry) => entry.prNumber === layer.prNumber);
     return member?.seamState?.trim().toLowerCase() === "approved" && sameHead(member.seamReviewedSha, layer.headSha);
 }
-function vortexFindingsLeftForPerson(stack, layer) {
+function vortexFindingsLeftForPerson(stack, layer, nowMs) {
     if (layerAgentsBusy(layer).cyclone)
         return false;
     if (seamApprovedAtHead(stack, layer))
         return false;
     return vortexImportantFindingsHeldAtHead(layer) ||
-        (vortexChangesRequestedAtHead(layer) && cycloneHandoffAtHead(stack, layer) !== null);
+        (vortexChangesRequestedAtHead(layer) && cycloneHandoffAtHead(stack, layer, nowMs) !== null);
 }
 function quotaSkippedReview(layer) {
     const review = layer.vortexReview;
@@ -310,7 +335,7 @@ function headChecksRerunning(layer) {
     return layer.ciStatus === "pending" && !!checks && checks.failure === 0 && checks.pending > 0 && checks.cancelledOnly !== true;
 }
 /** Shared live-fact precedence; bounce history is only passed for the candidate. */
-function layerAttention(stack, layer, queue, cursor) {
+function layerAttention(stack, layer, queue, cursor, nowMs) {
     const none = { blocker: null, reason: null, bounceKind: null };
     if (stack.archivedAt)
         return none;
@@ -363,7 +388,7 @@ function layerAttention(stack, layer, queue, cursor) {
             if (landing && !landGateIsPending(landing))
                 return hardBlock(landing, "land_gate");
         }
-        if (vortexFindingsLeftForPerson(stack, layer))
+        if (vortexFindingsLeftForPerson(stack, layer, nowMs))
             return hardBlock(VORTEX_FINDINGS_NEED_PERSON, "vortex_findings_need_person");
     }
     if (!bounce || !kind || recoverable || !layer || queue.some((entry) => ["queued", "running", "waiting"].includes(entry.state)))
@@ -682,7 +707,7 @@ export function agentsCannotClear(reason, stack, layer) {
         return false;
     return AGENTS_CANNOT_CLEAR.includes(reason);
 }
-export function stackRepair(stack, attention, layer, bounce, queueWait = null) {
+export function stackRepair(stack, attention, layer, bounce, queueWait = null, nowMs = Date.now()) {
     if (!attention || !layer || attention.prNumber !== layer.prNumber)
         return null;
     const reason = attention.reason;
@@ -866,7 +891,7 @@ export function stackRepair(stack, attention, layer, bounce, queueWait = null) {
     }
     if (reason === "vortex_findings_need_person") {
         const findings = `gh api repos/${stack.owner}/${stack.repo}/pulls/${layer.prNumber}/reviews`;
-        const handoff = cycloneHandoffAtHead(stack, layer);
+        const handoff = cycloneHandoffAtHead(stack, layer, nowMs);
         return {
             kind: "vortex_findings",
             prNumber: layer.prNumber,
@@ -874,7 +899,7 @@ export function stackRepair(stack, attention, layer, bounce, queueWait = null) {
             branch: layer.branch,
             handoff,
             findings,
-            steps: `Vortex ${vortexImportantFindingsHeldAtHead(layer) ? "left Important findings" : "requested changes"} on ${layer.branch} at ${layer.headSha ?? "its live head"} and Cyclone left them for a person${handoff ? ` (${cycloneHandoffWords(handoff, cycloneHandoffDetailAtHead(layer))})` : ""}, so nothing will patch them and Auto land waits. Read the newest Vortex review and its inline comments (${findings}), verify each finding against ${layer.branch} at its live remote head, fix the real ones with the smallest patch, run the tests, confirm the remote head is still ${layer.headSha ?? "the head you started from"}, then an ordinary git push (no force). If a finding is wrong, tell the human; mg dismiss ${stack.owner}/${stack.repo}#${layer.prNumber} --head <sha> --review <id> dismisses that review. Do not retarget the PR base.`,
+            steps: `Vortex ${vortexImportantFindingsHeldAtHead(layer) ? "left Important findings" : "requested changes"} on ${layer.branch} at ${layer.headSha ?? "its live head"} and Cyclone left them undone${handoff ? ` (${cycloneHandoffWords(handoff, cycloneHandoffDetailAtHead(layer))})` : ""}, so nothing will patch them and Auto land waits. You fix them: read the newest Vortex review and its inline comments (${findings}), verify each finding against ${layer.branch} at its live remote head, fix the real ones with the smallest patch, run the tests, confirm the remote head is still ${layer.headSha ?? "the head you started from"}, then an ordinary git push (no force). Dismiss a finding you verified is wrong yourself: mg dismiss ${stack.owner}/${stack.repo}#${layer.prNumber} --head <sha> --review <id> --finding <id> --reason <why> --evidence <link>. Ask the human only for a product or design decision. Do not retarget the PR base.`,
         };
     }
     if (reason === "ci_failed" || attention.bounceKind === "ci_failure") {
@@ -964,7 +989,7 @@ export function stackBlockers(stack, entries = [], cursor = {}, nowMs = Date.now
     for (const layer of open) {
         const selected = layer.prNumber === candidate?.prNumber;
         const inScope = selected || !candidate || layer.position > candidate.position;
-        let result = layerAttention(stack, layer, selected ? queue : [], cursor);
+        let result = layerAttention(stack, layer, selected ? queue : [], cursor, nowMs);
         let disarmed;
         if (!result.blocker && selected) {
             disarmed = disarmingBounce(stack, queue);
@@ -1071,7 +1096,7 @@ export function stackBlockers(stack, entries = [], cursor = {}, nowMs = Date.now
     if (busy.length && attention && classified && agentsCannotClear(classified.reason, stack, attentionLayer)) {
         held = { ...attention, actAfter: "agents_idle", waitingOn: busy.map((entry) => entry.agent) };
         shownIssues = [attention, ...issues];
-        repair = stackRepair(stack, classified, attentionLayer, undefined, queueWait);
+        repair = stackRepair(stack, classified, attentionLayer, undefined, queueWait, nowMs);
         attention = null;
         bounce = undefined;
     }
@@ -1081,7 +1106,7 @@ export function stackBlockers(stack, entries = [], cursor = {}, nowMs = Date.now
         bounce = undefined;
     }
     else {
-        repair = landMissing?.repair ?? stackRepair(stack, classified, attentionLayer, bounce, queueWait);
+        repair = landMissing?.repair ?? stackRepair(stack, classified, attentionLayer, bounce, queueWait, nowMs);
     }
     if (!attention) {
         const next = found.find((item) => !layerBusy(item.layer));
@@ -1089,7 +1114,7 @@ export function stackBlockers(stack, entries = [], cursor = {}, nowMs = Date.now
             attention = next.issue;
             repair = next.repair !== undefined
                 ? next.repair
-                : stackRepair(stack, { ...next.issue, reason: next.reason }, next.layer, next.bounce, queueWait);
+                : stackRepair(stack, { ...next.issue, reason: next.reason }, next.layer, next.bounce, queueWait, nowMs);
             bounce = next.bounce;
             if (next.layer)
                 agents = layerAgents(next.layer);

package/dist/stack-dto.d.ts

@@ -59,6 +59,7 @@ export type StackVortexReviewView = {
     phase: string | null;
     /** Earliest live job start while `reviewing`; null when lease-only. */
     started_at: string | null;
+    settled_at?: string | null;
     /** Stop control visibility: true only while a pass can actually be cancelled. */
     stoppable: boolean;
     /** Which table spoke: the authority row, a live job, a lease, or nothing. */
@@ -225,6 +226,7 @@ export type StackLayerDto = {
     cycloneConflictPendingSince?: string | null;
     cycloneCiHandoff?: StackCycloneHandoff | null;
     cycloneCiPendingSince?: string | null;
+    cycloneFindingsTakenAtHead?: boolean;
     conflictDetail: string | null;
     restackError?: RestackError | null;
     lastRestackedSha: string | null;

package/dist/ui/banner.js

@@ -224,6 +224,9 @@ const WHATS_NEW = {
     "0.3.62": [
         "Watch wakes for a blocker on any layer",
     ],
+    "0.3.63": [
+        "Stack create starts a new stack unless --extend",
+    ],
 };
 function densityFromVariant(variant) {
     if (variant === "mini" || variant === "nano")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm",
-  "version": "0.3.62",
+  "version": "0.3.63",
   "description": "Mergestorm CLI (mg) — local reviews & stacked PRs. MIT; build from source: https://github.com/marginsystems/mergestorm-cli",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,14 @@
   },
   "exports": {
     ".": "./dist/cli.js",
-    "./client": "./dist/client/index.js"
+    "./client": {
+      "mergestorm-source": "./src/client/index.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./skill": {
+      "mergestorm-source": "./src/commands/skill.ts",
+      "default": "./dist/commands/skill.js"
+    }
   },
   "homepage": "https://mergestorm.ai/docs#review-jobs-api",
   "repository": {

package/skill/SKILL.md

@@ -48,7 +48,7 @@ Cursor `~/.cursor/mcp.json`:
 
 ## Preconditions
 
-1. Prefer the `mergestorm` MCP server. Call `whoami`. If MCP is missing, require `mg` on PATH with `mg whoami --json` exit 0. If neither is available, stop and print the install one-liner above.
+1. Prefer the `mergestorm` MCP server. Call `whoami`. If MCP is missing, require `mg` on PATH with `mg whoami --json` exit 0. If neither is available, stop and print the install one-liner above. A hosted connection to the Mergestorm MCP server, the kind a chat agent uses, has no `review_submit`: it cannot read your checkout. With only that connection, tell the human that this review runs where the branch is checked out, with `mg` or a local MCP server, and stop. Do not install `mg` yourself to get around it.
 2. Call `credits` (or `mg credits --json`). If remaining standard credits are 0, say so and stop.
 
 Ignored bot authors live in Settings → Vortex ("Ignore bot PR authors"), not Agents. Local `review_submit` is a manual review and is not an ignore-list skip.

package/skill/mergestorm-bounce-watch/SKILL.md

@@ -5,7 +5,9 @@ description: Watch stacks explicitly named by the human while Auto land is on, p
 
 # Mergestorm bounce watch
 
-Use only these shipped Mergestorm MCP tools: `stack_wait`, `stack_status`, `queue_status`, and `stack_set` with `auto_land: true` only at enrollment on the human's request or as "Re-arm after a bounce" allows. Use local checkout, test, and Git operations to make the patch, and the `mg stack watch` CLI command to wait in the background. Auto land owns landing.
+Use only these shipped Mergestorm MCP tools (plus `cyclone_start` and `cyclone_job` for the hosted handoff below): `stack_wait`, `stack_status`, `queue_status`, and `stack_set` with `auto_land: true` only at enrollment on the human's request or as "Re-arm after a bounce" allows. Use local checkout, test, and Git operations to make the patch, and, where the `mg` CLI is installed, the `mg stack watch` command to wait in the background. Auto land owns landing.
+
+A chat agent that reaches Mergestorm only through the hosted MCP tools has no checkout it can push and no `mg`. It hands each fix a commit would make to Cyclone: `cyclone_start` with task `resolve_conflicts` for a merge conflict, `fix_ci` for a failing check, or `fix_findings` for Vortex findings, then `cyclone_job` with its `dispatch_id` until the job is pushed, completed or failed. It waits with `stack_wait` and does not install `mg`.
 
 ## Who fixes what
 
@@ -17,7 +19,7 @@ A stack watch is done only when the stack is landed, or when the human takes it
 
 ## Waiting in the background
 
-The CLI watcher monitors the stack but cannot wake an agent by itself. Use the background handoff only when the host has a confirmed notification that resumes this task. A confirmed notification is a host feature you can name that turns the command's exit or matching output into your next turn; a process left running, or output written to a log or terminal you do not read, is not one. Without one, keep using `stack_wait` with `watch.next.args`, or tell the human that automatic follow-up is unavailable before ending the turn. Do not claim the task will resume just because a shell process is running. Do not subscribe to GitHub events. With a confirmed notification:
+This section needs the `mg` CLI where you run commands. Without it, skip this section and keep calling `stack_wait` with `watch.next.args`. The CLI watcher monitors the stack but cannot wake an agent by itself. Use the background handoff only when the host has a confirmed notification that resumes this task. A confirmed notification is a host feature you can name that turns the command's exit or matching output into your next turn; a process left running, or output written to a log or terminal you do not read, is not one. Without one, keep using `stack_wait` with `watch.next.args`, or tell the human that automatic follow-up is unavailable before ending the turn. Do not claim the task will resume just because a shell process is running. Do not subscribe to GitHub events. With a confirmed notification:
 
 1. Run `mg stack watch <stack-id>` as a background command (add `--head <sha>` right after you pushed that SHA) with a notification on output matching `MS-WATCH (ATTENTION|LANDED)`, then end your turn. The watcher runs the same stack wait against the Mergestorm API in slices of at most 300s, carries the cursor (`enrolled_head_sha`, `after_finished_at`, `bounce_id`) from one slice to the next, and prints nothing while the stack is `waiting` or `in_progress`, including `busy[]` holds and `actAfter: "agents_idle"`. It spends no model tokens while it waits. Ending your turn while it runs is not ending the task. Every `watch.next` carries this command as `watch.next.background`.
 2. It prints one line and exits for one of three reasons:
@@ -48,7 +50,7 @@ A stack whose layers are all merged into `mg-stack-N` but has no open land PR re
 3. `attention` always means something for you to fix. A land gate that is only waiting (`landGatePending` with `ci_pending` or another `*_pending` / `*_running` reason on the land PR) returns `in_progress`, not `attention`: keep watching. On `attention`, read `repair` when present: it names the blocked PR's `branch` and the concrete fix. For `restack_conflict` and `merge_conflict` it gives `liveParent` (the sibling PR head, or `mg-stack-N` once the lower layers are merged or promoted, or the land PR's base such as `main` when the blocked PR is the land PR, never `mg-park-*`) and the conflicted `files`; a null `liveParent` means stop and tell the human. For `ci_failure` it names the failing check. A stack whose `autoLandOff.reason` is `bounced` (a `merge_failed`, `gh_error`, or `ci_timeout` bounce turned Auto land off and nobody took the stack back since) returns `attention` with the blocker `Auto land off after <kind> bounce`, the bounce in `issues[]`, and a `repair` of kind `auto_land_off`; handle it as "Re-arm after a bounce" describes. A stack whose review unit was abandoned because a human moved its bottom PR off `mg-stack-N` returns `attention` with the blocker `Review unit abandoned: based on <base>` and a `repair` of kind `unit_abandoned`: do not patch or retarget anything. Ask the human whether to re-root it: if at least two PRs remain open, tell them that `mg stack adopt owner/repo#<bottom PR>` re-roots it on a new review unit; with only one open PR, re-adopting will not create a review unit, so tell them to close and resubmit it to create a fresh stack, then stop. Auto land records why it is waiting in the stack's `autoLandWait` (`reason`, `prNumber`, `headSha`, `since`), and the watch returns `attention` on that PR when the wait cannot clear on its own: a failing check Auto land reads live on GitHub while the ledger may still show CI green (blocker `CI failed — Auto land reads a failing check on GitHub at this head`, `repair` kind `ci_failure`); a check pending for 45 minutes (`repair` kind `ci_pending`: find the check that never finished and re-run it, or tell the human when no workflow reports it); no approving Vortex review for 30 minutes with no Vortex run working (`repair` kind `vortex_not_green`: fix or dismiss the findings, or tell the human when no review exists at the head); and a promote GitHub refused 3 times with `merge_failed`, after which Auto land stops retrying that head (`repair` kind `promote_failed`: fix the cause on the PR and push a new head, or tell the human when the cause is outside the PR; never toggle Auto land yourself for it). The watch also returns `attention` when GitHub refuses to let Mergestorm read the head's check runs or commit statuses (blocker `Mergestorm cannot read ... on this head`, `repair` kind `ci_unreadable`: do not patch or push; tell the human to grant the Mergestorm GitHub App the permission the repair names), and when any other wait reason has held for 45 minutes, a land gate left pending or running on the land PR included (blocker `Auto land has waited <N>m: <reason in plain words>`, `repair` kind `auto_land_waiting`: read `stack_status`, fix what a commit on the named branch can fix, otherwise tell the human what Auto land waits for and since when). A merge queue entry that has sat queued for 45 minutes with nothing working on it or ahead of it returns `attention` with the blocker `Merge queue stuck: ...` and a `repair` whose kind is queue_stalled: do not patch or push; tell the human. A Vortex review skipped because the PR author is on the ignored authors list, or because reviews are turned off for the repository, returns `attention` at once with a `repair` of kind `vortex_skipped`; a Vortex retry that is scheduled (`Vortex hit a temporary error on this head and will retry by itself`) is a wait listed in `issues[]`, never `attention`. `Review failed` carries a `repair` of kind `vortex_failed`: comment `@mergestorm-vortex review` on the PR or push a new commit, and tell the human if it fails again. A PR open on `mg-stack-N` that is not a layer of the stack returns `attention` at once with the blocker `The land PR cannot be queued: ...` and a `repair` of kind `members_remaining`: do not patch or push; close, retarget or adopt that PR (a draft or fork PR cannot be adopted). A layer whose live head has a Vortex verdict that requests changes after Cyclone left those findings for a person (a hold directive, the Vortex patch cap, auto-patch off, no billing, a batch it gave up on, or a PR state it could not read) returns `attention` with the blocker `Vortex findings need a person` and a `repair` of kind `vortex_findings` naming the Cyclone reason (`handoff`) and where the review is (`findings`): verify each finding against the checkout, fix the real ones with the smallest patch and an ordinary push, and tell the human about the ones you judge wrong. `repair` does not replace the checks below. On `attention`, fix the named PR: `prNumber` and `headSha` identify the blocked PR, while `currentCandidate` identifies the promote candidate. The gate covers the bottom and its direct child only when the child has current-head DIRTY on the live bottom branch. A GitHub DIRTY whose `parentBranch` starts with `mg-park-` is not that gate. Refresh `stack_status`; use `queue_status` with the same `stack_id` when bounce details are needed. Verify the blocker still applies to the current PR head. Never treat `verifyHeadSha` as the current head: it is a queue verification SHA and can be stale or synthetic. Compare the live PR branch head, the current stack layer head, and the checkout before editing. Read the live PR head with `git ls-remote origin refs/heads/<branch>` or `gh api repos/OWNER/REPO/pulls/N --jq .head.sha`. If you need CI logs, use `gh run list --branch <branch>`, `gh run view <run-id> --log-failed`, or `gh api repos/OWNER/REPO/commits/SHA/check-runs`. Read GitHub only through git and these REST calls; do not use other `gh pr` subcommands. Restack `clean` does not mean mergeable or CI-green. Attention is a diagnosis, not permission to mutate stack or queue policy; the only policy change you make is the re-arm in "Re-arm after a bounce". A bounce is the reason to look, not the moment to commit. `stack_wait` and `stack_status` hold the blocked PR's attention themselves while Vortex or Cyclone is still working on that PR, whatever the blocker (a red CI failure, a merge conflict, a bounce, Draft, a failed restack or review): they return `in_progress` instead of `attention`, with `busy[]` naming the PR (`prNumber`, `headSha`), the `blocker`, and the `agent` (`vortex` or `cyclone`), and `agents` carrying that PR's `vortexStatus`, `cycloneStatus`, `vortexReview`, and `busy` flags. `in_progress` with a nonempty `busy[]` means do not patch yet: keep calling `stack_wait` with the same cursor until that work has finished and the watch returns `attention`, then make the follow-up commit. You do not need an extra `stack_status` refresh each slice for this check. A nonempty `busy[]` reports still-working agents on that PR's current head. Vortex holds when `vortexReview` is `reviewing` at the head, an unfinished vortex `agentRuns` row at the head is `reviewing`, or an unfinished vortex run at the head is `queued` and started within the last 15 minutes (with no `agentRuns` or `vortexReview` on the layer, `vortexStatus` `reviewing` holds). Cyclone holds when `cycloneStatus` is `patching`, an unfinished cyclone `agentRuns` row is `patching`, or the server sees a live Cyclone patch lease or an open Cyclone check run on the head. `seam_pending` alone, and a `queued` run older than 15 minutes, are not treated as work in progress. `all_clear`, `findings`, `skipped`, `failed`, `throttled`, `awaiting_fix`, and a null status are finished. A queued Vortex run holds for at most 15 minutes; reviewing and patching hold until the run finishes or its lease or check run is cleared. A blocker no Vortex or Cyclone run can clear is not hidden by the hold: a merge conflict vs the live parent, a restack `Conflict` or `Restack failed` (a parked freeze included), a Draft PR, `Seam review pending, no review running`, or `Review skipped, out of review quota`. For those the envelope stays `in_progress` but names the blocker in the top-level `blocker`, `prNumber`, `headSha`, and `issues[]`, with `actAfter: "agents_idle"`, `waitingOn` listing the busy agents, and `repair` when there is one. Plan the fix from it, but do not patch, merge, or push while `actAfter` is set: keep calling `stack_wait` with the same cursor, and act when a snapshot after the agents finish returns `attention`; a Cyclone push can change or clear the blocker, so re-read it then. Blockers the agents can change (a red CI failure, a failed review, seam findings, a bounce) keep the plain hold: `blocker` is null, `actAfter` is null, and only `busy[]` names them. If a hold looks stuck, refresh `stack_status` and tell the human. Do not turn Cyclone off or Auto land off, and do not turn Auto land on to end the wait; turn it on only as "Re-arm after a bounce" allows. If the remote head moves while you wait, stop and tell the human.
 4. Use a clean worktree on that named PR's head branch and record the remote starting SHA. Fix the current blocker with the smallest patch, and run the relevant checks. For conflicts, the live parent is the sibling PR head or the unit branch (`mg-stack-N`, Mergestorm's owned trunk, not an alias for main) — not the DTO `parentBranch` when that field starts with `mg-park-*`. If `parentBranch` is `mg-park-*`, never merge or rebase onto it; if the real live parent is unknown, stop. The land PR is the one PR whose head is `mg-stack-N`: its live parent is its base (`main`), and merging that base into `mg-stack-N` with an ordinary push is its conflict repair, the same as for any other layer. Cyclone patches Vortex findings on a land PR when auto-patch is on for that stack; every other land PR blocker, a conflict with main or failing CI included, is yours: when `busy[]` shows no Cyclone run on it, fix it with the smallest patch on `mg-stack-N` and push with an ordinary push, never a force push; while Cyclone is patching findings on it the envelope stays `in_progress` with `busy[]`, so wait. For a conflict, prefer merging that live parent into the PR branch, resolving locally, then an ordinary push. Do not click Dashboard Continue yourself: Continue is a human action, and you relay it to the human only when step 5 or a `repair` names it. When the live parent is a sibling, never rebase onto trunk or `mg-stack-N` instead. Parked-freeze DIRTY alone needs no conflict patch. Leave GitHub bases as Mergestorm set them: the bottom of a 2+ PR stack is based on `mg-stack-N`, layer 2 on layer 1, PR3+ on `mg-park-*`.
 5. CI-only fixes may run while Cyclone auto-patch is still on for the stack. Auto-patch may stay on, and you still wait until the current Vortex run and the current Cyclone run on that PR have finished before the follow-up commit. When the gate is clean, inspect `issues[]` and fix a live upstack CI failure one PR at a time, refreshing the gate before the next PR. Do not use higher-layer bounce history as a patch target. Do not fight Cyclone: if the remote head moved, stop and tell the human. Do not take over Cyclone's review-finding work while it is active; if the blocker requires that or a policy/queue action rather than a concrete patch, stop and explain what needs human attention. On a `Seam findings` blocker, read that PR's seam finding, the Vortex review "Integration review — IU <n> seam" (`gh api repos/OWNER/REPO/pulls/N/reviews` and `gh api repos/OWNER/REPO/pulls/N/comments`), and patch its concrete findings on that PR's head; a "Decision required" seam finding needs a human, so tell them and do not guess. A seam finding you verified is wrong is recorded with `mg dismiss` (the audited dismissal in `mergestorm-pr-loop`) at that PR's live head and that seam review's id; a `mergestorm-loop: dismiss` comment alone does not clear the seam gate. On `Seam review failed`, do not patch; tell the human, unless a new push already has a seam re-review held in `busy[]`. On `Seam review pending, no review running`, do not patch; tell the human: the seam review was skipped (usually because the monthly review limit is reached) and nothing re-runs it until they raise the limit and click Continue on the stack, or push a new head. On `Seam review stuck in reviewing, no review running`, `Seam re-review pending, no review running`, or `Seam verdict is for an older head, no review running` (repair kind `seam_review_stuck`), do not patch or push; tell the human: no seam review is queued or running for that PR's live head, and clicking Continue on the stack re-queues it (a new pushed head also does). On `Review skipped, out of review quota`, do not patch; tell the human: the review credit limit for the period is reached and nothing re-reviews that head until they raise the limit and push a new head or re-run the review.
-6. Recheck Auto land (off is expected only after a disarming bounce you are handling) and the remote PR head (`git ls-remote origin refs/heads/<branch>`) immediately before pushing. Commit the patch and push the PR head with an ordinary push. A rebase onto that same live parent followed by force-with-lease is allowed only if the remote is still exactly the SHA you started from and Cyclone did not move it; use an explicit lease bound to that starting SHA. This exception never permits rebasing onto a parked freeze or substituting trunk / the unit for a sibling parent. If the remote head moved or the push is rejected because it moved, stop; do not rebase and retry.
+6. Recheck Auto land (off is expected only after a disarming bounce you are handling) and the remote PR head (`git ls-remote origin refs/heads/<branch>`) immediately before pushing. Also call `queue_status` with the `stack_id`: while an entry of the stack is `queued`, `running`, or `waiting`, do not push. The queue is verifying the diff that was reviewed when it was queued; a push that changes that diff bounces the entry `head_moved` and stops the batch it is in, which re-runs CI for every PR in that batch. Do not cancel the entry. Keep the fix on a local branch and keep watching: when the entry bounces, push the fix to this PR; when the stack lands, open the fix as a follow-up PR (`mg stack create <name> --onto main`, then `mg stack submit`) and tell the human its number. Commit the patch and push the PR head with an ordinary push. A rebase onto that same live parent followed by force-with-lease is allowed only if the remote is still exactly the SHA you started from and Cyclone did not move it; use an explicit lease bound to that starting SHA. This exception never permits rebasing onto a parked freeze or substituting trunk / the unit for a sibling parent. If the remote head moved or the push is rejected because it moved, stop; do not rebase and retry.
 7. After your successful push, leave a clean worktree and keep watching the named stack. Start a new watch cycle with `enrolled_head_sha` set to the SHA you pushed (in the background: `mg stack watch <stack-id> --head <pushed-sha>`). If you handled a bounce, retain the returned `cursor.afterFinishedAt` as `after_finished_at` and `cursor.bounceId` as `bounce_id` so that attempt is not handled again. Keep these selectors unchanged across subsequent retries. Continue watching; do not enqueue anything. If the bounce you handled turned Auto land off, turn it back on as "Re-arm after a bounce" allows; if that section does not allow it, report and stop.
 
 ## Re-arm after a bounce

package/skill/mergestorm-pr-loop/SKILL.md

@@ -19,10 +19,13 @@ mg skill install --claude --cursor --agents
 
 ## Preconditions (in order)
 
+A hosted-only agent (no checkout of the PR head; see 5) checks 1, then follows 5 instead of 2 to 4: those gates are for the local patching loop it does not run, and the `mg login` sign-in in 4 needs a shell it does not have.
+
 1. There is an already-open GitHub PR on a Vortex-monitored repo. No PR, wrong skill.
 2. Auto-patch (Cyclone) must be off for this PR so you are the only patcher. Do not take anyone's word for it: the settings API and the PR's stack are the source of truth, and step 1 of the loop verifies them before anything else runs. Cyclone is off for the PR when its adopted stack has `autoPatchOverride` `false`, or when that override is unset and the account `auto_patch_enabled` is `false`.
 3. The Bearer key and the Cyclone GitHub App install must be the same Mergestorm account. `stack_list` / `stack_status` expose `keyUserId`, `cycloneInstallUserId`, and `cycloneOwnerMatch`. Cyclone apply always uses the install account, not the key. If those identities differ, your `settings_get` mute reading is about the wrong person.
 4. `whoami` works on the `mergestorm` MCP server (or `mg whoami --json` exits 0). Otherwise stop and ask for install, or sign in yourself: run `mg login --start`, send the person the link it prints, and after they approve it run `mg login --finish`.
+5. You have a checkout of the PR head that you can push. A chat agent that reaches Mergestorm only through the hosted MCP tools, with no such checkout, does not run this loop: Cyclone patches the PR. Call `cyclone_start` with task `fix_findings` for the PR, then call `cyclone_job` with its `dispatch_id` until the job is pushed, completed or failed, and tell the human what it pushed.
 
 ## Loop (in order)
 
@@ -55,9 +58,10 @@ mg skill install --claude --cursor --agents
      - A refusal (stale_head, review_mismatch, unknown_finding, forbidden) means nothing was written. Re-read the pass at the live head; do not retry with another review's ids.
      - The seam gate clears only when every finding of that seam review is dismissed. Once every Vortex Blocker (error finding) at the live head is dismissed (every Core review merged into that head, not only the one you name), the Vortex gate clears at that head; while any is open, or a Vortex review of the head is still running or incomplete, it stays shut and `gate.vortex.message` says why. The result's `gate` says whether either cleared; CI and Auto land policy are unchanged. For a stack PR, follow `watch.next` (the next `stack_wait` call).
 6. Patch on the PR head branch only.
-7. Push that head branch with an ordinary push. If the push is rejected because the remote branch moved, another patcher already pushed for this pass. Do not rebase, do not force, do not retry the push: stop and tell the human that a second patcher is active on this PR.
-8. Call `review_wait_pr` again with `after_sha` set to the SHA you just pushed (7+ hex) and `timeout_s` 45. If the last envelope you acted on has that same `head_sha` (no new commit, for example a re-review requested on the same head), also pass `after_pass` set to that envelope's saved `pass`, so the wait cannot hand you that attempt again. For a freshly pushed SHA omit `after_pass`; its first pass is 1. Keep `after_sha` and `after_pass` unchanged across 45s timeout retries; never replace `after_pass` with the `pass` of an in-progress envelope. `pass` reads one exact attempt; `timeout_s` 0 reads once without waiting. An envelope whose `head_sha` is an older commit is a previous pass, not yours; keep waiting.
-9. Repeat from step 4 until a stop rule fires.
+7. If the PR is a layer of a stack, call `queue_status` with that `stack_id` before you push. While an entry of the stack is `queued`, `running`, or `waiting`, do not push: the queue is verifying the reviewed diff, and a push that changes it bounces the entry `head_moved` and stops the batch it is in, which re-runs CI for every PR in that batch. Do not cancel the entry. Keep the fix on a local branch and wait for the entry to finish: when it bounces, continue with the push; when it lands, open the fix as a follow-up PR (`mg stack create <name> --onto main`, then `mg stack submit`), tell the human its number, and stop this loop. Without a live entry, continue. Auto land needs no change: a push before it queues the PR only restarts its wait on the new head.
+8. Push that head branch with an ordinary push. If the push is rejected because the remote branch moved, another patcher already pushed for this pass. Do not rebase, do not force, do not retry the push: stop and tell the human that a second patcher is active on this PR.
+9. Call `review_wait_pr` again with `after_sha` set to the SHA you just pushed (7+ hex) and `timeout_s` 45. If the last envelope you acted on has that same `head_sha` (no new commit, for example a re-review requested on the same head), also pass `after_pass` set to that envelope's saved `pass`, so the wait cannot hand you that attempt again. For a freshly pushed SHA omit `after_pass`; its first pass is 1. Keep `after_sha` and `after_pass` unchanged across 45s timeout retries; never replace `after_pass` with the `pass` of an in-progress envelope. `pass` reads one exact attempt; `timeout_s` 0 reads once without waiting. An envelope whose `head_sha` is an older commit is a previous pass, not yours; keep waiting.
+10. Repeat from step 4 until a stop rule fires.
 
 ## Stop rules