mergestorm 0.3.62 → 0.3.64

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;
 };
@@ -172,6 +180,7 @@ export declare function cmdStackWatch(args: string[], deps?: {
     loadConfig?: typeof loadConfig;
     runStackWatch?: typeof runStackWatch;
     signal?: AbortSignal;
+    writeMarker?: (line: string) => void;
 }): Promise<void>;
 export declare function cmdStackStatus(args: string[], deps?: {
     loadConfig?: typeof loadConfig;

package/dist/commands/stack.js

@@ -5,13 +5,13 @@ 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";
-import { runStackWatch, STACK_WATCH_EXIT } from "../stack-watch-loop.js";
+import { runStackWatch, STACK_WATCH_EXIT, stackWatchFailedLine } from "../stack-watch-loop.js";
 import { isMgParkBranch, planSubmitLayerBases } from "../submit-pr-base.js";
 import { ansi } from "../ui/ansi.js";
 import { runLineTabsBrowser } from "../ui/line-tabs.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]
@@ -62,7 +62,8 @@ const STACK_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]
     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
+    error twice, or 15 minutes with no stack read: timeouts, 5xx and rate limits, which it retries with backoff).
+    It also prints MS-WATCH ATTENTION failed when it cannot start (bad flags, no config), so it never exits without an MS-WATCH line unless you stop it; 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.
@@ -95,10 +96,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 +156,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 +536,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 +555,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 +563,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 +634,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 +668,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 +880,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 +1021,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 +1038,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 +1056,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 +1105,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 +1116,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}`),
     ]);
@@ -1173,7 +1214,7 @@ export async function cmdStackWait(args, deps = {}) {
         throw new CommandError(err.message, REVIEW_EXIT.timeout, "review_timeout");
     }
 }
-export async function cmdStackWatch(args, deps = {}) {
+async function startStackWatch(args, deps) {
     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 = [];
@@ -1246,6 +1287,30 @@ export async function cmdStackWatch(args, deps = {}) {
                 ...(afterFinishedAt ? { afterFinishedAt } : {}),
             } } : {}),
     });
+    return { stackId, result };
+}
+export async function cmdStackWatch(args, deps = {}) {
+    let started;
+    try {
+        started = await startStackWatch(args, deps);
+    }
+    catch (err) {
+        const valueFlags = new Set(["--until", "--ignore", "--max", "--head", "--bounce-id", "--after-finished-at"]);
+        let json = false;
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === "--json")
+                json = true;
+            else if (valueFlags.has(args[i]))
+                i++;
+        }
+        const marker = deps.writeMarker ?? (json ? console.error : console.log);
+        const stackId = args.find((arg, i) => UUID_RE.test(arg.trim()) && !valueFlags.has(args[i - 1]))?.trim() ?? "none";
+        marker(stackWatchFailedLine(stackId, err instanceof Error ? err.message : String(err)));
+        if (json)
+            console.log(JSON.stringify({ stackId, outcome: "failed" }));
+        throw err;
+    }
+    const { stackId, result } = started;
     if (result.exitCode === STACK_WATCH_EXIT.landed)
         return;
     const reason = result.outcome === "timeout"

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;
@@ -9,6 +10,7 @@ export declare function loadConfig(): Promise<Config>;
 export declare function saveConfig(cfg: Config): Promise<void>;
 export declare function clearConfig(): Promise<void>;
 export declare function apiBase(cfg: Config): string;
+export declare function resolveChatId(cfg: Config): string | undefined;
 export declare function resolveApiKey(cfg: Config): string | undefined;
 /** Short display form of a stored key (prefix only). */
 export declare function keyDisplay(key: string | undefined): string | null;

package/dist/config.js

@@ -30,9 +30,19 @@ 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(/\/$/, "");
+}
+const CHAT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function resolveChatId(cfg) {
+    if (cfg.ignoreEnv)
+        return undefined;
+    const chatId = process.env.MERGESTORM_CHAT_ID?.trim() ?? "";
+    return CHAT_ID.test(chatId) ? chatId.toLowerCase() : undefined;
 }
 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" | "git_failed" | "unknown_label" | "invalid_input" | "memory_off" | "memory_full" | "memory_unavailable";
 /** 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/memory-api.d.ts

@@ -0,0 +1,73 @@
+import { type Config } from "./config.js";
+export declare const MEMORY_MODES: readonly ["off", "on_request", "all"];
+export declare const MEMORY_SCOPES: readonly ["user", "repo"];
+export declare const MEMORY_KINDS: readonly ["rule", "style", "preference", "fact", "project"];
+export declare const MEMORY_SEARCH_LIMIT_MAX = 20;
+export type MemoryMode = (typeof MEMORY_MODES)[number];
+export type MemoryScope = (typeof MEMORY_SCOPES)[number];
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
+export type MemoryItem = {
+    id: string;
+    scope: MemoryScope;
+    repo: string | null;
+    kind: MemoryKind;
+    text: string;
+    source: string | null;
+    source_url: string | null;
+    created_at: string;
+    updated_at: string;
+};
+export type MemoryList = {
+    memory_mode: MemoryMode;
+    items: MemoryItem[];
+};
+export type MemorySearch = {
+    memory_mode: MemoryMode;
+    rules: MemoryItem[];
+    items: MemoryItem[];
+    total: number;
+};
+export type MemorySaved = {
+    id: string;
+    merged: boolean;
+};
+export type MemoryUpdated = {
+    id: string;
+    text: string;
+    kind?: MemoryKind;
+};
+export declare function memoryChatId(value?: string | null | undefined): string | null;
+export declare function isMemoryMode(value: unknown): value is MemoryMode;
+export declare function isMemoryKind(value: unknown): value is MemoryKind;
+export declare function isMemoryScope(value: unknown): value is MemoryScope;
+export declare function listMemories(filter?: {
+    scope?: MemoryScope;
+    repo?: string;
+    kind?: MemoryKind;
+}, cfg?: Config): Promise<MemoryList>;
+export declare function searchMemories(input: {
+    query: string;
+    repo?: string;
+    limit?: number;
+    chatId?: string | null;
+}, cfg?: Config): Promise<MemorySearch>;
+export declare function saveMemory(input: {
+    text: string;
+    kind: MemoryKind;
+    repo?: string | null;
+    chatId?: string | null;
+}, cfg?: Config): Promise<MemorySaved>;
+export declare function updateMemory(id: string, change: {
+    text: string;
+    kind?: MemoryKind;
+}, cfg?: Config): Promise<MemoryUpdated>;
+export declare function deleteMemory(id: string, cfg?: Config): Promise<{
+    id: string;
+    deleted: true;
+}>;
+export declare function getMemoryMode(cfg?: Config): Promise<{
+    memory_mode: MemoryMode;
+}>;
+export declare function setMemoryMode(mode: MemoryMode, cfg?: Config): Promise<{
+    memory_mode: MemoryMode;
+}>;

package/dist/memory-api.js

@@ -0,0 +1,69 @@
+import { apiFetch } from "./api.js";
+import { loadConfig } from "./config.js";
+import { CommandError, REVIEW_EXIT, rateLimitedMessage } from "./errors.js";
+export const MEMORY_MODES = ["off", "on_request", "all"];
+export const MEMORY_SCOPES = ["user", "repo"];
+export const MEMORY_KINDS = ["rule", "style", "preference", "fact", "project"];
+export const MEMORY_SEARCH_LIMIT_MAX = 20;
+const CHAT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function memoryChatId(value = process.env.MERGESTORM_CHAT_ID) {
+    const trimmed = value?.trim() ?? "";
+    return CHAT_ID.test(trimmed) ? trimmed.toLowerCase() : null;
+}
+export function isMemoryMode(value) {
+    return typeof value === "string" && MEMORY_MODES.includes(value);
+}
+export function isMemoryKind(value) {
+    return typeof value === "string" && MEMORY_KINDS.includes(value);
+}
+export function isMemoryScope(value) {
+    return typeof value === "string" && MEMORY_SCOPES.includes(value);
+}
+const KNOWN_CODES = new Set(["invalid_input", "not_found", "memory_off", "memory_full", "memory_unavailable", "payload_too_large"]);
+function memoryFailure(status, body, retryAfterSeconds, action) {
+    const row = (body && typeof body === "object" ? body : {});
+    if (status === 429 || row.error === "rate_limited") {
+        return new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", retryAfterSeconds !== undefined ? { retryAfterSeconds } : undefined);
+    }
+    const message = typeof row.message === "string" && row.message ? row.message : null;
+    const code = typeof row.error === "string" && KNOWN_CODES.has(row.error) ? row.error : undefined;
+    if (status === 404 && !code)
+        return new CommandError("This Mergestorm server does not manage memories yet.", 1, "not_found");
+    return new CommandError(message ?? `${action} (HTTP ${status})`, 1, code);
+}
+async function call(cfg, route, init, ok, action) {
+    const { status, body, retryAfterSeconds } = await apiFetch(cfg ?? (await loadConfig()), route, init);
+    if (!ok.includes(status))
+        throw memoryFailure(status, body, retryAfterSeconds, action);
+    return body;
+}
+function query(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params))
+        if (value !== undefined && value !== null && value !== "")
+            search.set(key, String(value));
+    const text = search.toString();
+    return text ? `?${text}` : "";
+}
+export function listMemories(filter = {}, cfg) {
+    return call(cfg, `/api/v1/memories${query(filter)}`, {}, [200], "Could not list memories");
+}
+export function searchMemories(input, cfg) {
+    return call(cfg, `/api/v1/memories/search${query({ query: input.query, repo: input.repo, limit: input.limit, chat_id: input.chatId })}`, {}, [200], "Could not search memories");
+}
+export function saveMemory(input, cfg) {
+    const json = { text: input.text, kind: input.kind, ...(input.repo ? { repo: input.repo } : {}), ...(input.chatId ? { chat_id: input.chatId } : {}) };
+    return call(cfg, "/api/v1/memories", { method: "POST", json }, [200, 201], "Could not save the memory");
+}
+export function updateMemory(id, change, cfg) {
+    return call(cfg, `/api/v1/memories/${encodeURIComponent(id)}`, { method: "PATCH", json: change }, [200], "Could not update the memory");
+}
+export function deleteMemory(id, cfg) {
+    return call(cfg, `/api/v1/memories/${encodeURIComponent(id)}`, { method: "DELETE" }, [200], "Could not delete the memory");
+}
+export function getMemoryMode(cfg) {
+    return call(cfg, "/api/v1/memories/mode", {}, [200], "Could not read the memory mode");
+}
+export function setMemoryMode(mode, cfg) {
+    return call(cfg, "/api/v1/memories/mode", { method: "PUT", json: { memory_mode: mode } }, [200], "Could not set the memory mode");
+}

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;
@@ -7,26 +8,28 @@ export declare const SERVER_PUBLISH_MAX_TOTAL_BYTES: number;
 export declare const SERVER_PUBLISH_MAX_COMMIT_BYTES: number;
 export declare const SERVER_PUBLISH_FILE_MODES: readonly ["100644", "100755", "120000"];
 export declare const SERVER_PUBLISH_HISTORY_SCAN = 500;
-export type GitRead = (args: string[], cwd: string) => Buffer;
+export type GitRead = (args: string[], cwd: string) => Buffer | Promise<Buffer>;
+export declare const READ_ONLY_GIT: Set<string>;
 export declare function readGit(args: string[], cwd: string): Buffer;
-export declare function readCommitHeader(read: GitRead, sha: string, cwd: string): {
+export declare function readCommitHeader(read: GitRead, sha: string, cwd: string): Promise<{
     tree: string;
     parents: string[];
     author: StackPublicationIdentity;
     committer: StackPublicationIdentity;
     message: string;
-};
+}>;
 export declare function readCommitChanges(read: GitRead, parent: string, sha: string, cwd: string, budget: {
     changes: number;
     bytes: number;
-}): StackPublicationChange[];
-export declare function readPublicationCommits(read: GitRead, from: string, to: string, cwd: string): StackPublicationCommit[];
+}): Promise<StackPublicationChange[]>;
+export declare function readPublicationCommits(read: GitRead, from: string, to: string, cwd: string): Promise<StackPublicationCommit[]>;
 export type ServerPublishInput = {
     cfg: Config;
     cwd: string;
     owner: string;
     repo: string;
     branch: string;
+    localRef?: string;
     baseBranch: string;
     localBaseRef?: string;
     remoteBaseSha?: string;
@@ -39,6 +42,7 @@ export type ServerPublishDeps = {
     read?: GitRead;
     getStackPublication?: typeof getStackPublication;
     submitStackPublication?: typeof submitStackPublication;
+    assertBase?: (base: string) => void;
 };
 export type ServerPublishResult = StackPublication & {
     baseBranch: string;
@@ -54,17 +58,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>;