mergestorm 0.3.61 → 0.3.63

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,18 +52,20 @@ 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]
   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 watch <stack-id> [--until attention|landed] [--ignore <blocker-substring>] [--max <minutes>] [--head <sha>] [--json]
+  mergestorm stack watch <stack-id> [--until attention|landed] [--ignore <blocker-substring>] [--max <minutes>] [--head <sha>] [--bounce-id <id>] [--after-finished-at <iso>] [--json]
     Loops stack wait with the cursor and stays silent while the stack is waiting or in progress.
     Prints one MS-WATCH ATTENTION line and exits 3 on attention or on reads that keep failing (a permanent
     error twice, or 15 minutes of timeouts and 5xx, which it retries with backoff); prints MS-WATCH LANDED
     and exits 0 only for a confirmed landing, including a stack Mergestorm deleted after its queue entry landed. Other terminal reasons exit 3 with ATTENTION. Run it as a background command.
+    An ATTENTION line for a merge queue bounce ends with restart="mg stack watch <id> --bounce-id <id> --after-finished-at <iso>":
+    restart with that command (plus --head <sha> after a push) so a bounce you already handled is not reported again.
     --json writes exactly one JSON document to stdout and sends the MS-WATCH lines to stderr.
   mergestorm stack set <stack-id> [--auto-land on|off] [--auto-review on|off|default] [--auto-patch on|off|default] [--auto-resolve-conflicts on|off|default] [--auto-fix-ci on|off|default] [--json]
   mergestorm stack adopt <owner/repo>#<pr> [--auto-land on|off] [--auto-review on|off] [--auto-patch on|off] [--auto-resolve-conflicts on|off] [--auto-fix-ci on|off] [--json]
@@ -85,17 +87,21 @@ const STACK_USAGE = `usage:
   stack submit --server-side and stack publish need no GitHub credentials: mg
   reads your commits from the local repository and sends them to Mergestorm,
   which writes the commits and the branch on GitHub as the Surge App, opens the
-  pull request, and registers the stack with Auto patch pinned off. They never
+  pull request, and registers the stack. Auto patch follows the stack, the
+  repository and your account, like any other stack. They never
   run gh, git push or git fetch. stack publish does this for one branch and is
   how you send later commits to a branch that is already published. Mergestorm
   refuses to move a branch whose head on GitHub matches no local commit unless
   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) {
@@ -149,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() ?? "";
@@ -522,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;
@@ -539,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) {
@@ -558,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.`));
@@ -603,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));
@@ -634,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}` +
@@ -782,9 +817,6 @@ export async function cmdStackSubmit(args, deps = {}) {
         }
     }
     if (serverSide) {
-        if (autoPatch === true) {
-            throw new CommandError("--server-side publishes your own commits and keeps Auto patch off for the stack. Drop --auto-patch on, or submit without --server-side.", REVIEW_EXIT.usage, "usage");
-        }
         const parked = plans.find((plan) => plan.githubBase == null);
         if (parked) {
             throw new CommandError(`Layer ${parked.branch} opens onto a park freeze, which --server-side does not mint. ` +
@@ -796,6 +828,7 @@ export async function cmdStackSubmit(args, deps = {}) {
         const remoteHeads = new Map();
         const published = [];
         let publishedStackId = null;
+        let publishedAutoPatch = null;
         for (const plan of plans) {
             if (!branchExistsFn(plan.branch, cwd)) {
                 throw new CommandError(`Stack layer branch missing locally: ${plan.branch}`);
@@ -825,6 +858,7 @@ export async function cmdStackSubmit(args, deps = {}) {
             });
             remoteHeads.set(plan.branch, result.head.sha);
             publishedStackId = result.stack.id;
+            publishedAutoPatch = result.stack.autoPatchOverride;
             published.push({
                 branch: plan.branch,
                 base: result.baseBranch,
@@ -834,19 +868,20 @@ export async function cmdStackSubmit(args, deps = {}) {
                 tree: result.head.tree,
             });
         }
-        const { autoEnqueueWhenReady: _autoLand, autoPatchOverride: _autoPatch, ...otherOverrides } = policy ?? {};
+        const { autoEnqueueWhenReady: _autoLand, ...otherOverrides } = policy ?? {};
         if (publishedStackId && Object.keys(otherOverrides).length > 0) {
             await (deps.setStackPolicy ?? setStackPolicy)(publishedStackId, otherOverrides, config);
         }
         await saveStackMetaFn(removeActiveStack(meta), cwd);
         const watch = publishedStackId ? openStackWatch(publishedStackId) : null;
         if (asJson) {
-            console.log(JSON.stringify({ owner, repo, layers: published, stackId: publishedStackId, trunk: meta.trunk, chain: null, serverSide: true, autoPatchOverride: false, watch }, null, 2));
+            console.log(JSON.stringify({ owner, repo, layers: published, stackId: publishedStackId, trunk: meta.trunk, chain: null, serverSide: true, autoPatchOverride: otherOverrides.autoPatchOverride ?? publishedAutoPatch, watch }, null, 2));
             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} with Auto patch off`));
+            lines.push(ansi.brightGreen(`  Registered stack ${publishedStackId}`));
         lines.push(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
         if (watch)
             lines.push(...stackWatchTextLines(watch).map((line) => `  ${line}`));
@@ -963,9 +998,6 @@ export async function cmdStackSubmit(args, deps = {}) {
         await registerPr(opened[opened.length - 1].prNumber);
     }
     else {
-        if (opened.length === 0) {
-            throw new CommandError("No pull requests to register after submit.");
-        }
         await registerPr(opened[0].prNumber);
     }
     const data = adoptData;
@@ -988,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.`));
@@ -1004,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",
@@ -1022,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;
@@ -1057,7 +1094,7 @@ export async function cmdStackPublish(args, deps = {}) {
             ...(status.head ? [ansi.dim(`  head ${status.head.sha} (tree ${status.head.tree ?? "unknown"})`)] : []),
             ...(status.pr ? [ansi.dim(`  #${status.pr.number} → ${status.pr.base}  ${status.pr.url}`)] : []),
             ...(status.stack
-                ? [ansi.dim(`  stack ${status.stack.id}  auto-patch ${status.stack.autoPatchOverride === false ? "off" : "not pinned off"}  auto-land ${status.stack.autoLand ? "on" : "off"}`)]
+                ? [ansi.dim(`  stack ${status.stack.id}  auto-patch ${status.stack.autoPatchOverride === null ? "default" : status.stack.autoPatchOverride ? "on" : "off"}  auto-land ${status.stack.autoLand ? "on" : "off"}`)]
                 : []),
         ]);
         return;
@@ -1067,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) {
@@ -1077,7 +1115,8 @@ 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(`  Registered stack ${result.stack.id} with Auto patch off`),
+        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}`),
     ]);
 }
@@ -1175,13 +1214,15 @@ export async function cmdStackWait(args, deps = {}) {
     }
 }
 export async function cmdStackWatch(args, deps = {}) {
-    const usage = "usage: mergestorm stack watch <stack-id> [--until attention|landed] [--ignore <blocker-substring>] [--max <minutes>] [--head <sha>] [--json]";
+    const usage = "usage: mergestorm stack watch <stack-id> [--until attention|landed] [--ignore <blocker-substring>] [--max <minutes>] [--head <sha>] [--bounce-id <id>] [--after-finished-at <iso>] [--json]";
     const fail = (detail) => new CommandError(detail ? `${usage}\n${detail}` : usage, REVIEW_EXIT.usage, "usage");
     const positional = [];
     const ignore = [];
     let until = "attention";
     let maxMinutes;
     let head;
+    let bounceId;
+    let afterFinishedAt;
     let json = false;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -1212,6 +1253,17 @@ export async function cmdStackWatch(args, deps = {}) {
             if (!/^[0-9a-f]{7,40}$/i.test(head))
                 throw fail("--head must be a commit SHA");
         }
+        else if (flag === "--bounce-id") {
+            bounceId = value();
+            if (!/^[0-9a-z-]{1,64}$/i.test(bounceId))
+                throw fail("--bounce-id must be a merge queue entry id");
+        }
+        else if (flag === "--after-finished-at") {
+            const raw = value();
+            if (Number.isNaN(Date.parse(raw)))
+                throw fail("--after-finished-at must be an ISO timestamp");
+            afterFinishedAt = new Date(raw).toISOString();
+        }
         else if (arg.startsWith("-"))
             throw fail();
         else
@@ -1227,7 +1279,12 @@ export async function cmdStackWatch(args, deps = {}) {
         json,
         signal: deps.signal,
         ...(maxMinutes !== undefined ? { maxMs: maxMinutes * 60_000 } : {}),
-        ...(head ? { cursor: { stackId: stackId.trim().toLowerCase(), enrolledHeadSha: head.toLowerCase() } } : {}),
+        ...(head || bounceId || afterFinishedAt ? { cursor: {
+                stackId: stackId.trim().toLowerCase(),
+                enrolledHeadSha: head ? head.toLowerCase() : null,
+                ...(bounceId ? { bounceId } : {}),
+                ...(afterFinishedAt ? { afterFinishedAt } : {}),
+            } } : {}),
     });
     if (result.exitCode === STACK_WATCH_EXIT.landed)
         return;
@@ -1273,7 +1330,7 @@ export async function cmdStackStatus(args, deps = {}) {
         freshCursor: true,
     });
     if (asJson) {
-        console.log(JSON.stringify({ ...stack, held, repair, queueWait, watch }, null, 2));
+        console.log(JSON.stringify({ ...stack, attention, held, repair, queueWait, watch }, null, 2));
         return;
     }
     const lines = formatStackHuman(stack, false);
@@ -1287,7 +1344,7 @@ export async function cmdStackStatus(args, deps = {}) {
     }
     if (queueWait && !attention)
         lines.push(`  Queue: #${queueWait.prNumber} ${queueWait.text}`);
-    lines.push(...[...stackHeldLine(held), ...stackRepairLine(repair), ...stackWatchTextLines(watch)].map((line) => `  ${line}`));
+    lines.push(...[...stackHeldLine(attention ? null : held), ...stackRepairLine(repair), ...stackWatchTextLines(watch)].map((line) => `  ${line}`));
     await present("Stack status", lines);
 }
 /** Human summary lines for a `stack set` write, one per flag. */
@@ -1446,7 +1503,7 @@ export async function cmdStack(args, options = {}) {
         return cmdStackAdopt(rest);
     if (sub === "restack")
         return cmdStackRestack(rest);
-    if (sub === "land" || sub === "land-next")
+    if (sub === "land")
         return cmdStackLand(rest);
     throw new CommandError(`${STACK_USAGE}\nunknown stack subcommand: ${sub}`);
 }

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/repo-identity.d.ts

@@ -1,6 +1,4 @@
-export declare const LEGACY_STACK_META_REL: string;
 export declare function gitTopLevel(cwd?: string): string;
-export declare function gitCommonDir(cwd?: string): string;
 /**
  * Each worktree has its own authoring state.
  * Independent clones remain isolated even when they point at the same remote.
@@ -9,4 +7,3 @@ export declare function stableRepoId(cwd?: string): string;
 export declare function cliStacksRoot(): string;
 export declare function repoStateDir(cwd?: string, stacksRoot?: string): string;
 export declare function stackMetaPath(cwd?: string, stacksRoot?: string): string;
-export declare function legacyStackMetaPath(cwd?: string): string;

package/dist/repo-identity.js

@@ -4,7 +4,6 @@ import path from "node:path";
 import { mergestormHome } from "./config.js";
 import { CommandError } from "./errors.js";
 import { git } from "./git.js";
-export const LEGACY_STACK_META_REL = path.join(".mergestorm", "stack.json");
 /** Classify git "not a repo" failures once at the boundary; callers match on code. */
 function rethrowIfNotARepo(err) {
     const detail = err instanceof Error ? err.message : String(err);
@@ -21,25 +20,6 @@ export function gitTopLevel(cwd = process.cwd()) {
         rethrowIfNotARepo(err);
     }
 }
-export function gitCommonDir(cwd = process.cwd()) {
-    let raw;
-    try {
-        raw = git(["rev-parse", "--git-common-dir"], cwd).trim();
-    }
-    catch (err) {
-        rethrowIfNotARepo(err);
-    }
-    const absolute = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
-    try {
-        return realpathSync(absolute);
-    }
-    catch (err) {
-        if (err?.code === "ENOENT") {
-            throw new CommandError(`git common directory is missing (${absolute}); this is often a linked worktree whose main repository was deleted. Run \`mg stack reset --force\` to clear local pre-submit state.`, 1, "not_a_repo");
-        }
-        throw err;
-    }
-}
 /**
  * Each worktree has its own authoring state.
  * Independent clones remain isolated even when they point at the same remote.
@@ -67,6 +47,3 @@ export function repoStateDir(cwd = process.cwd(), stacksRoot = cliStacksRoot())
 export function stackMetaPath(cwd = process.cwd(), stacksRoot = cliStacksRoot()) {
     return path.join(repoStateDir(cwd, stacksRoot), "stack.json");
 }
-export function legacyStackMetaPath(cwd = process.cwd()) {
-    return path.join(gitTopLevel(cwd), LEGACY_STACK_META_REL);
-}

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;
@@ -190,7 +192,6 @@ export declare const AUTO_LAND_CI_FAILED_BLOCKER = "CI failed \u2014 Auto land r
 export declare const AUTO_LAND_WAIT_ATTENTION_MS: number;
 export declare const AUTO_LAND_CI_UNREADABLE_ATTENTION_MS: number;
 export declare function autoLandWaitLayer(stack: StackDto): StackLayerDto | undefined;
-export declare function autoLandWaitBlocker(stack: StackDto, layer: StackLayerDto, nowMs: number): string | null;
 export declare const MERGE_QUEUE_STALL_ATTENTION_MS: number;
 export type StackQueueWait = {
     prNumber: number;
@@ -217,26 +218,12 @@ 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): {
-    attention: null;
-    held: StackHeldBlocker;
-    issues: StackBlocker[];
-    currentCandidate: {
-        prNumber: number;
-        headSha: string | null;
-    } | null;
-    bounce: undefined;
-    busy: StackAgentBusy[];
-    agents: StackLayerAgents | null;
-    repair: StackRepairHint | null;
-    landGatePending: StackLandGatePending | null;
-    queueWait: StackQueueWait | null;
-} | {
     attention: StackBlocker | null;
-    held: null;
+    held: StackHeldBlocker | null;
     issues: StackBlocker[];
     currentCandidate: {
         prNumber: number;