mergestorm 0.3.5 → 0.3.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Margin Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
-# mergestorm CLI
+# Mergestorm CLI
 
-Review a local git diff with MergeStorm without opening a GitHub PR — for local loops and CI. Diffs are reviewed by the same engine as PR reviews and each review consumes one standard credit.
+Review a local git diff with Mergestorm without opening a GitHub PR — for local loops and CI. Diffs are reviewed by the same engine as PR reviews and each review consumes one standard credit.
 
 Requires **Node.js 22+**.
 
@@ -24,6 +24,19 @@ mg login
 
 After install, both `mergestorm` and `mg` invoke the same CLI.
 
+## Source
+
+Public source (MIT): [github.com/marginsystems/mergestorm-cli](https://github.com/marginsystems/mergestorm-cli).
+Tags there match npm versions (`v0.3.7`, …).
+
+```bash
+git clone https://github.com/marginsystems/mergestorm-cli.git
+cd mergestorm-cli
+npm install
+npm run build
+node dist/cli.js --help
+```
+
 ### From this monorepo (development / local UI testing)
 
 You do **not** need to bump/publish npm to try shell layout changes. From the repo root:
@@ -48,14 +61,14 @@ mergestorm          # uses your local build
 On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a **full-width** welcome panel (logo + status on the left, tips / what's new on the right) and a **full-width** bordered input box with a live `/` slash-command dropdown. Non-TTY (CI/pipes) prints usage instead — no hanging prompt.
 
 ```
-╭─ mergestorm v0.3.5 ──────────────────────────────────────────────────────────╮
+╭─ mergestorm v0.3.7 ──────────────────────────────────────────────────────────╮
 │      ▟██████████▛       Tips for getting started                             │
 │       ▜████████▛          review      review main...HEAD                     │
 │        ▝▜████▛▘           stack       create → submit → restack → land       │
 │          ▜██▛             /help       list all commands                      │
 │           ██                                                                 │
-│           ▝▘            What's new in v0.3.5                                 │
-│  ● msk…  ·  maelstrom     • stack submit fills PR body from tip commit       │
+│           ▝▘            What's new in v0.3.7                                 │
+│  ● msk…  ·  maelstrom     • MIT license + public source (mergestorm-cli)       │
 │  [████░░░░░░░░░░] 12% used                                                   │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
@@ -99,13 +112,16 @@ mergestorm stack adopt <owner/repo>#<pr>  Import an existing open PR chain
 mergestorm stack restack <stack-id>  Restack descendants
 mergestorm stack land <stack-id>     Land the bottom open PR
 mergestorm stack auto-land on|off <stack-id>  Toggle auto-land when green
+mergestorm stack reset --force  Clear local authoring state (not branches/PRs)
 ```
 
 `mg` is a short alias for `mergestorm` (same binary), e.g. `mg stack create`. Happy path: **create → commit → submit → restack → land**. `stack adopt` is for importing a chain that already exists on GitHub (legacy / Graphite). Restack/land use the same login key (`/api/v1/stacks`).
 
-`stack create` is local-only: it checks out a new branch from the current tip (or `--onto <branch>`), discovers trunk (`main` / `master` / `origin/HEAD`, overridable with `--trunk`), and appends `{ branch, parentBranch }` under **`.mergestorm/stack.json`**. No GitHub or API calls.
+`stack create` is local-only: it checks out a new branch from the current tip (or `--onto <branch>`), discovers trunk (`main` / `master` / `origin/HEAD`, overridable with `--trunk`), and records `{ branch, parentBranch }` in CLI-managed state under **`~/.mergestorm/stacks/<repo-id>/stack.json`**. The CLI updates this automatically; never edit it. Linked worktrees share state, while independent clones remain isolated. Creating onto trunk with a non-empty active stack starts a new one. No repository file, GitHub call, or API call is made.
+
+`stack submit` walks the **active** local stack: `git push -u origin` each layer, opens a PR with `gh` (`--base` = parent or trunk; 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/PR auth is your local `git` + `gh auth` — not a GitHub App installation token.
 
-`stack submit` walks that meta: `git push -u origin` each layer, opens a PR with `gh` (`--base` = parent or trunk; skips heads that already have an open PR; body from the tip commit — Summary + Test plan, preserving Fixes/Closes/Resolves), then registers the stack with `POST /api/v1/stacks/adopt` internally (Mergestorm API key). Push/PR auth is your local `git` + `gh auth` — not a Cyclone app token.
+Legacy repo-local `.mergestorm/stack.json` state migrates automatically on the next stack command. If local authoring state is stale or malformed, use `mg stack reset --force`; this clears only pre-submit CLI state and never deletes branches, PRs, or registered stacks.
 
 ### `login`
 
@@ -119,7 +135,7 @@ Removes `~/.mergestorm/config.json` so the stored key is no longer used.
 
 ### `review [base] [head]`
 
-Collects `git diff base...head` (default `main...HEAD`), attaches the changed file contents (up to 40 files, skipping files > 400 KB), auto-attaches context from `./.mergestorm/**/*.md|*.txt`, submits the job, and polls until it finishes (~3 min max). The thread slug is derived from the current branch (`local/<branch>`), so repeated runs on the same branch chain their findings.
+Collects `git diff base...head` (default `main...HEAD`), attaches the changed file contents (up to 40 files, skipping files > 400 KB), submits the job, and polls until it finishes (~3 min max). The thread slug is derived from the current branch (`local/<branch>`), so repeated runs on the same branch chain their findings. Programmatic callers can provide explicit review context through the Review Jobs API.
 
 ```bash
 mergestorm review              # main...HEAD
@@ -141,10 +157,6 @@ Require a logged-in key and API support for `GET /api/v1/me` and `GET /api/v1/re
 
 `branches` calls `GET /api/v1/threads` for recently active review threads (branches). On a TTY it opens an arrow-key selector; Enter loads that thread's job timeline. `chain [slug]` is the direct timeline view — omit the slug to use `local/<current-git-branch>` (same slug `review` stamps).
 
-## Context pack (`.mergestorm/`)
-
-Any `*.md` / `*.txt` files under `./.mergestorm/` (one level of nesting) are attached as context so the reviewer understands intent, conventions, or migration notes without you resending history.
-
 ## Environment
 
 | Variable | Purpose | Default |
@@ -155,5 +167,6 @@ Any `*.md` / `*.txt` files under `./.mergestorm/` (one level of nesting) are att
 
 ## See also
 
-- [Review Jobs API reference](https://github.com/marginsystems/mergestorm/blob/main/docs/review-jobs-api.md) — raw HTTP endpoints, webhook signing, thread chains, quota.
+- [Public source — mergestorm-cli](https://github.com/marginsystems/mergestorm-cli)
 - [Docs — Review Jobs API & CLI](https://mergestorm.ai/docs#review-jobs-api) — product docs on the site.
+- [npm — mergestorm](https://www.npmjs.com/package/mergestorm)

package/dist/api.d.ts

@@ -106,7 +106,7 @@ export type StackDto = {
     owner: string;
     repo: string;
     trunkBranch: string;
-    autoLandWhenGreen: boolean;
+    autoPromoteWhenGreen: boolean;
     layers: StackLayerDto[];
 };
 /** List stacks (Bearer GET /api/v1/stacks). */
@@ -119,7 +119,7 @@ export declare function restackStack(stackId: string, cfg?: Config): Promise<unk
 export declare function landNextStack(stackId: string, cfg?: Config, opts?: {
     prNumber?: number;
 }): Promise<unknown>;
-/** Toggle auto-land when green (Bearer PATCH /api/v1/stacks/:id). */
-export declare function setStackAutoLand(stackId: string, autoLandWhenGreen: boolean, cfg?: Config): Promise<unknown>;
+/** Toggle auto-promote when green (Bearer PATCH /api/v1/stacks/:id). */
+export declare function setStackAutoPromote(stackId: string, autoPromoteWhenGreen: boolean, cfg?: Config): Promise<unknown>;
 /** Recently reviewed branches/threads (Bearer GET /api/v1/threads). */
 export declare function listThreads(limit?: number, cfg?: Config): Promise<ThreadListItem[]>;

package/dist/api.js

@@ -125,9 +125,9 @@ export async function landNextStack(stackId, cfg, opts) {
         : {};
     return stackMutation(stackId, "/land-next", "POST", json, "Failed to land next", cfg);
 }
-/** Toggle auto-land when green (Bearer PATCH /api/v1/stacks/:id). */
-export async function setStackAutoLand(stackId, autoLandWhenGreen, cfg) {
-    return stackMutation(stackId, "", "PATCH", { autoLandWhenGreen }, "Failed to update auto-land", cfg);
+/** Toggle auto-promote when green (Bearer PATCH /api/v1/stacks/:id). */
+export async function setStackAutoPromote(stackId, autoPromoteWhenGreen, cfg) {
+    return stackMutation(stackId, "", "PATCH", { autoPromoteWhenGreen }, "Failed to update auto-promote", cfg);
 }
 /** Recently reviewed branches/threads (Bearer GET /api/v1/threads). */
 export async function listThreads(limit = 20, cfg) {

package/dist/cli.js

@@ -30,13 +30,14 @@ function usage() {
   mergestorm chain [slug]         Branch review-chain timeline (default: current)
   mergestorm whoami [--json]      Key + plan + API base
   mergestorm thread <slug>        Jobs in a review thread
-  mergestorm stack create [name]  New local stack layer (.mergestorm/stack.json)
-  mergestorm stack submit         Push layers, open chained PRs, register stack
+  mergestorm stack create [name]  New local stack layer (CLI-managed authoring state)
+  mergestorm stack submit         Push active local stack, open PRs, register stack
+  mergestorm stack reset --force  Clear this repo's pre-submit authoring state
   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 stack descendants
   mergestorm stack land <stack-id>      Land bottom PR (or promote into unit)
-  mergestorm stack auto-land on|off <stack-id>  Toggle auto-land when green
+  mergestorm stack auto-promote on|off <stack-id>  Toggle auto-promote when green
 
   mg is a short alias for mergestorm (same binary).
 

package/dist/commands/login.js

@@ -25,7 +25,7 @@ async function loginWithKey(existingRl) {
     const rl = existingRl ?? createInterface({ input, output });
     const ownRl = !existingRl;
     try {
-        const key = (await rl.question("Paste your MergeStorm API key (msk_live_...): ")).trim();
+        const key = (await rl.question("Paste your Mergestorm API key (msk_live_...): ")).trim();
         if (!key.startsWith("msk_live_")) {
             throw new CommandError("Key should start with msk_live_");
         }

package/dist/commands/review.d.ts

@@ -4,7 +4,7 @@ export type ReviewOptions = {
     interactive?: boolean;
 };
 /** Parse `origin` remote into GitHub owner/repo when possible. */
-export declare function parseGithubOriginRepo(): {
+export declare function parseGithubOriginRepo(cwd?: string): {
     owner: string;
     repo: string;
 } | null;

package/dist/commands/review.js

@@ -1,12 +1,12 @@
 import { apiFetch, getMe } from "../api.js";
 import { loadConfig } from "../config.js";
 import { CommandError, DetachedError } from "../errors.js";
-import { collectChangedFiles, collectContextFiles, git } from "../git.js";
+import { collectChangedFiles, git } from "../git.js";
 import { ansi } from "../ui/ansi.js";
 /** Parse `origin` remote into GitHub owner/repo when possible. */
-export function parseGithubOriginRepo() {
+export function parseGithubOriginRepo(cwd = process.cwd()) {
     try {
-        const url = git(["remote", "get-url", "origin"]).trim();
+        const url = git(["remote", "get-url", "origin"], cwd).trim();
         if (!url)
             return null;
         const m = url.match(/^(?:https?:\/\/|git@)?github\.com[:/]([A-Za-z0-9_-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/i);
@@ -44,11 +44,10 @@ export async function cmdReview(args, opts = {}) {
         return;
     }
     const files = await collectChangedFiles(base, head);
-    const context_files = await collectContextFiles(process.cwd());
     const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]).trim() || "local";
     const thread = `local/${branch}`.replace(/[^a-zA-Z0-9._/-]/g, "-").slice(0, 120);
     const originRepo = parseGithubOriginRepo();
-    console.log(`Submitting review (${Buffer.byteLength(diff, "utf8")} byte diff, ${files.length} file(s), ${context_files.length} context file(s))…`);
+    console.log(`Submitting review (${Buffer.byteLength(diff, "utf8")} byte diff, ${files.length} file(s))…`);
     const { status, body } = await apiFetch(cfg, "/api/v1/reviews", {
         method: "POST",
         json: {
@@ -59,7 +58,6 @@ export async function cmdReview(args, opts = {}) {
             head_label: head,
             diff,
             files,
-            context_files,
         },
         signal: opts.signal,
     });

package/dist/commands/stack.d.ts

@@ -12,4 +12,5 @@ export declare function parseStackCreateArgs(args: string[]): {
     trunk?: string;
     asJson: boolean;
 };
+export declare function parseStackResetArgs(args: string[]): void;
 export declare function cmdStack(args: string[]): Promise<void>;

package/dist/commands/stack.js

@@ -1,20 +1,22 @@
-import { adoptStack, landNextStack, listStacks, restackStack, setStackAutoLand, } from "../api.js";
+import { adoptStack, landNextStack, listStacks, restackStack, setStackAutoPromote, } from "../api.js";
 import { loadConfig } from "../config.js";
 import { CommandError } from "../errors.js";
 import { createPr, findOpenPrNumber, requireGh } from "../gh.js";
 import { branchExists, createBranchFromHead, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty, } from "../git-stack.js";
 import { buildPrBodyFromCommit } from "../pr-body.js";
-import { appendLayer, loadStackMeta, saveStackMeta, } from "../stack-meta.js";
+import { gitTopLevel } from "../repo-identity.js";
+import { activeLayers, appendLayer, emptyStackMeta, loadStackMeta, removeActiveStack, resetStackMeta, saveStackMeta, selectStackForCreate, } from "../stack-meta.js";
 import { ansi } from "../ui/ansi.js";
 import { parseGithubOriginRepo } from "./review.js";
 const STACK_USAGE = `usage:
   mergestorm stack create [name] [--onto <branch>] [--trunk <branch>] [--json]
   mergestorm stack submit [--json]
+  mergestorm stack reset --force
   mergestorm stack list [--json]
   mergestorm stack adopt <owner/repo>#<pr>
   mergestorm stack restack <stack-id> [--json]
   mergestorm stack land <stack-id> [--json]
-  mergestorm stack auto-land on|off <stack-id> [--json]
+  mergestorm stack auto-promote on|off <stack-id> [--json]
 
   stack submit opens PRs with a body generated from each layer tip commit.
   stack land promotes into the review unit when one exists; otherwise lands
@@ -49,7 +51,7 @@ export function parseAdoptTarget(args) {
 }
 function formatStackHuman(s) {
     const lines = [];
-    const auto = s.autoLandWhenGreen ? " · auto-land" : "";
+    const auto = s.autoPromoteWhenGreen ? " · auto-promote" : "";
     lines.push(`  ${ansi.bold(`${s.owner}/${s.repo}`)}  trunk=${s.trunkBranch}${auto}`);
     lines.push(`  ${ansi.dim(s.id)}`);
     if (s.layers.length === 0) {
@@ -107,9 +109,20 @@ export function parseStackCreateArgs(args) {
     }
     return { name, onto, trunk, asJson };
 }
+export function parseStackResetArgs(args) {
+    if (args.length !== 1 || args[0] !== "--force") {
+        throw new CommandError("usage: mergestorm stack reset --force\nClears only CLI-managed pre-submit state; branches, PRs, and registered stacks are unchanged.");
+    }
+}
 async function cmdStackCreate(args) {
     const { name, onto, trunk: trunkFlag, asJson } = parseStackCreateArgs(args);
     const cwd = process.cwd();
+    try {
+        gitTopLevel(cwd);
+    }
+    catch {
+        throw new CommandError("Not in a git repository. Run `mg stack create` from inside the repository whose stack you want to author.");
+    }
     if (worktreeDirty(cwd)) {
         throw new CommandError("Working tree is dirty. Commit or stash changes before `stack create`.");
     }
@@ -127,16 +140,16 @@ async function cmdStackCreate(args) {
     let meta = await loadStackMeta(cwd);
     const trunk = trunkFlag?.trim() || meta?.trunk || discoverTrunk(cwd);
     if (!meta) {
-        meta = { version: 1, trunk, layers: [] };
+        meta = emptyStackMeta(trunk);
     }
     else if (trunkFlag?.trim() && meta.trunk !== trunk) {
-        throw new CommandError(`Stack trunk is ${meta.trunk}; refusing --trunk ${trunk}. Edit .mergestorm/stack.json or start fresh.`);
+        throw new CommandError(`Stack trunk is ${meta.trunk}; refusing --trunk ${trunk}. Run \`mg stack reset --force\` to discard local pre-submit state.`);
+    }
+    try {
+        meta = selectStackForCreate(meta, parentBranch);
     }
-    // Parent must be trunk or an existing layer (linear local stack).
-    if (meta.layers.length > 0 &&
-        parentBranch !== meta.trunk &&
-        !meta.layers.some((l) => l.branch === parentBranch)) {
-        throw new CommandError(`Parent ${parentBranch} is not trunk (${meta.trunk}) or a stack layer. Use --onto <branch>.`);
+    catch (err) {
+        throw new CommandError(err instanceof Error ? err.message : String(err));
     }
     try {
         createBranchFromHead(branch, cwd);
@@ -144,10 +157,9 @@ async function cmdStackCreate(args) {
     catch (err) {
         throw new CommandError(err instanceof Error ? err.message : String(err));
     }
-    let next;
     try {
-        next = appendLayer(meta, { branch, parentBranch });
-        await saveStackMeta(next, cwd);
+        meta = appendLayer(meta, { branch, parentBranch });
+        await saveStackMeta(meta, cwd);
     }
     catch (err) {
         try {
@@ -156,13 +168,22 @@ async function cmdStackCreate(args) {
         catch { /* rollback best-effort */ }
         throw new CommandError(err instanceof Error ? err.message : String(err));
     }
+    const layers = activeLayers(meta);
     if (asJson) {
-        console.log(JSON.stringify({ branch, parentBranch, trunk: next.trunk, meta: next }, null, 2));
+        console.log(JSON.stringify({
+            branch,
+            parentBranch,
+            trunk: meta.trunk,
+            active: meta.active,
+            stacks: meta.stacks.length,
+            layers,
+            meta,
+        }, null, 2));
         return;
     }
     console.log(ansi.green(`  Created ${branch} (onto ${parentBranch})`));
-    console.log(ansi.dim(`  trunk: ${next.trunk} · layers: ${next.layers.length}`));
-    console.log(ansi.dim(`  meta: .mergestorm/stack.json`));
+    console.log(ansi.dim(`  trunk: ${meta.trunk} · local stacks: ${meta.stacks.length} · active layers: ${layers.length}`));
+    console.log(ansi.dim("  authoring state: managed automatically outside the repository"));
 }
 async function cmdStackSubmit(args) {
     const asJson = args.includes("--json");
@@ -170,18 +191,25 @@ async function cmdStackSubmit(args) {
         throw new CommandError("usage: mergestorm stack submit [--json]");
     }
     const cwd = process.cwd();
+    try {
+        gitTopLevel(cwd);
+    }
+    catch {
+        throw new CommandError("Not in a git repository. Run `mg stack submit` from inside the repo whose stack you want to push.");
+    }
     const meta = await loadStackMeta(cwd);
-    if (!meta || meta.layers.length === 0) {
-        throw new CommandError("No local stack layers. Run `mg stack create` (and commit) before `stack submit`.");
+    const layers = meta ? activeLayers(meta) : [];
+    if (!meta || layers.length === 0) {
+        throw new CommandError("No local stack layers. Run `mg stack create` (then commit your code) before `stack submit`.");
     }
-    const origin = parseGithubOriginRepo();
+    const origin = parseGithubOriginRepo(cwd);
     if (!origin) {
         throw new CommandError("Could not parse GitHub owner/repo from `origin`. Set a github.com remote and retry.");
     }
     const { owner, repo } = origin;
     requireGh(cwd);
     const opened = [];
-    for (const layer of meta.layers) {
+    for (const layer of layers) {
         const base = layer.parentBranch || meta.trunk;
         if (!branchExists(layer.branch, cwd)) {
             throw new CommandError(`Stack layer branch missing locally: ${layer.branch}`);
@@ -230,6 +258,8 @@ async function cmdStackSubmit(args) {
         throw new CommandError("Stack was not registered");
     }
     const stackId = data.stack.id;
+    // Drop the submitted local stack so the next create onto trunk starts fresh.
+    await saveStackMeta(removeActiveStack(meta), cwd);
     if (asJson) {
         console.log(JSON.stringify({
             owner,
@@ -253,6 +283,11 @@ async function cmdStackSubmit(args) {
     }
     console.log(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard/stacks"));
 }
+async function cmdStackReset(args) {
+    parseStackResetArgs(args);
+    await resetStackMeta(process.cwd());
+    console.log(ansi.green("  Cleared CLI-managed pre-submit stack state. Branches, PRs, and registered stacks were not changed."));
+}
 async function cmdStackList(args) {
     const asJson = args.includes("--json");
     const cfg = await loadConfig();
@@ -343,17 +378,17 @@ async function cmdStackAutoLand(args) {
     const asJson = args.includes("--json");
     const filtered = args.filter((a) => a !== "--json");
     const mode = filtered[0]?.toLowerCase();
-    const id = requireStackId(filtered[1], "usage: mergestorm stack auto-land on|off <stack-id>");
+    const id = requireStackId(filtered[1], "usage: mergestorm stack auto-promote on|off <stack-id>");
     if (mode !== "on" && mode !== "off") {
-        throw new CommandError("usage: mergestorm stack auto-land on|off <stack-id>");
+        throw new CommandError("usage: mergestorm stack auto-promote on|off <stack-id>");
     }
     const cfg = await loadConfig();
-    const body = await setStackAutoLand(id, mode === "on", cfg);
+    const body = await setStackAutoPromote(id, mode === "on", cfg);
     if (asJson) {
         console.log(JSON.stringify(body, null, 2));
         return;
     }
-    console.log(ansi.green(`  Auto-land ${mode} for ${id}`));
+    console.log(ansi.green(`  Auto-promote ${mode} for ${id}`));
 }
 export async function cmdStack(args) {
     const sub = args[0]?.toLowerCase();
@@ -365,6 +400,8 @@ export async function cmdStack(args) {
         return cmdStackCreate(rest);
     if (sub === "submit")
         return cmdStackSubmit(rest);
+    if (sub === "reset")
+        return cmdStackReset(rest);
     if (sub === "list" || sub === "ls")
         return cmdStackList(rest);
     if (sub === "adopt")
@@ -373,7 +410,11 @@ export async function cmdStack(args) {
         return cmdStackRestack(rest);
     if (sub === "land" || sub === "land-next")
         return cmdStackLand(rest);
-    if (sub === "auto-land" || sub === "autoland")
+    if (sub === "auto-promote" ||
+        sub === "autopromote" ||
+        sub === "auto-land" ||
+        sub === "autoland") {
         return cmdStackAutoLand(rest);
+    }
     throw new CommandError(`${STACK_USAGE}\nunknown stack subcommand: ${sub}`);
 }

package/dist/config.d.ts

@@ -3,6 +3,7 @@ export type Config = {
     apiKey?: string;
     apiBase?: string;
 };
+export declare function mergestormHome(): string;
 export declare function configPath(): string;
 export declare function loadConfig(): Promise<Config>;
 export declare function saveConfig(cfg: Config): Promise<void>;

package/dist/config.js

@@ -2,8 +2,11 @@ import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 export const DEFAULT_API = "https://api.mergestorm.ai";
+export function mergestormHome() {
+    return path.join(homedir(), ".mergestorm");
+}
 export function configPath() {
-    return path.join(homedir(), ".mergestorm", "config.json");
+    return path.join(mergestormHome(), "config.json");
 }
 export async function loadConfig() {
     try {

package/dist/git-stack.d.ts

@@ -2,8 +2,10 @@
 export declare function currentBranch(cwd?: string): string | null;
 /**
  * True when the worktree has staged/unstaged/untracked changes that should
- * block `stack create`. Ignores `.mergestorm/stack.json` so local stack meta
- * written by create does not prevent the next layer.
+ * block `stack create`. Stack authoring metadata lives outside the worktree.
+ * Legacy repo-local `.mergestorm/stack.json` is ignored because `loadStackMeta`
+ * migrates it out of the worktree during `stack create`; counting it as dirty
+ * would block that migration and every subsequent create.
  */
 export declare function worktreeDirty(cwd?: string): boolean;
 /**

package/dist/git-stack.js

@@ -13,8 +13,10 @@ export function currentBranch(cwd = process.cwd()) {
 }
 /**
  * True when the worktree has staged/unstaged/untracked changes that should
- * block `stack create`. Ignores `.mergestorm/stack.json` so local stack meta
- * written by create does not prevent the next layer.
+ * block `stack create`. Stack authoring metadata lives outside the worktree.
+ * Legacy repo-local `.mergestorm/stack.json` is ignored because `loadStackMeta`
+ * migrates it out of the worktree during `stack create`; counting it as dirty
+ * would block that migration and every subsequent create.
  */
 export function worktreeDirty(cwd = process.cwd()) {
     const out = git(["status", "--porcelain"], cwd);
@@ -27,7 +29,9 @@ export function worktreeDirty(cwd = process.cwd()) {
         const pathPart = (status.includes("R") || status.includes("C"))
             ? trimmed.slice(3).split(" -> ").pop()?.trim() ?? ""
             : trimmed.slice(3).trim();
-        if (pathPart === ".mergestorm/stack.json" || pathPart.endsWith("/.mergestorm/stack.json")) {
+        if (pathPart.startsWith(".mergestorm/") ||
+            pathPart.endsWith("/.mergestorm/") ||
+            pathPart.endsWith("/.mergestorm/stack.json")) {
             continue;
         }
         return true;

package/dist/git.d.ts

@@ -1,8 +1,4 @@
 export declare function git(args: string[], cwd?: string): string;
-export declare function collectContextFiles(root: string): Promise<{
-    path: string;
-    content: string;
-}[]>;
 export declare function collectChangedFiles(base: string, head: string): Promise<{
     path: string;
     content: string;

package/dist/git.js

@@ -1,7 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { readdir, readFile, stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
-const CONTEXT_DIR = ".mergestorm";
 export function git(args, cwd = process.cwd()) {
     try {
         const result = spawnSync("git", args, { cwd, encoding: "utf8" });
@@ -14,36 +13,6 @@ export function git(args, cwd = process.cwd()) {
         throw new Error(`git ${args.join(" ")} failed: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-export async function collectContextFiles(root) {
-    const pack = path.join(root, CONTEXT_DIR);
-    let entries;
-    try {
-        entries = await readdir(pack, { withFileTypes: true });
-    }
-    catch {
-        return [];
-    }
-    const files = [];
-    for (const entry of entries) {
-        if (entry.isFile() &&
-            (entry.name.toLowerCase().endsWith(".md") || entry.name.toLowerCase().endsWith(".txt"))) {
-            const content = await readFile(path.join(pack, entry.name), "utf8");
-            files.push({ path: entry.name, content });
-        }
-        else if (entry.isDirectory() && !entry.name.startsWith(".")) {
-            const nested = await readdir(path.join(pack, entry.name), { withFileTypes: true }).catch(() => []);
-            for (const child of nested) {
-                if (child.isFile() &&
-                    (child.name.toLowerCase().endsWith(".md") || child.name.toLowerCase().endsWith(".txt"))) {
-                    const rel = `${entry.name}/${child.name}`;
-                    const content = await readFile(path.join(pack, entry.name, child.name), "utf8");
-                    files.push({ path: rel, content });
-                }
-            }
-        }
-    }
-    return files;
-}
 export async function collectChangedFiles(base, head) {
     const names = git(["diff", "--name-only", "--diff-filter=ACMR", `${base}...${head}`])
         .split("\n")

package/dist/repo-identity.d.ts

@@ -0,0 +1,12 @@
+export declare const LEGACY_STACK_META_REL: string;
+export declare function gitTopLevel(cwd?: string): string;
+export declare function gitCommonDir(cwd?: string): string;
+/**
+ * A physical clone and all its linked worktrees share one authoring state.
+ * Independent clones remain isolated even when they point at the same remote.
+ */
+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

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+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");
+export function gitTopLevel(cwd = process.cwd()) {
+    return realpathSync(git(["rev-parse", "--show-toplevel"], cwd).trim());
+}
+export function gitCommonDir(cwd = process.cwd()) {
+    const raw = git(["rev-parse", "--git-common-dir"], cwd).trim();
+    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.`);
+        }
+        throw err;
+    }
+}
+/**
+ * A physical clone and all its linked worktrees share one authoring state.
+ * Independent clones remain isolated even when they point at the same remote.
+ */
+export function stableRepoId(cwd = process.cwd()) {
+    return createHash("sha256").update(gitCommonDir(cwd)).digest("hex").slice(0, 20);
+}
+export function cliStacksRoot() {
+    return path.join(mergestormHome(), "stacks");
+}
+export function repoStateDir(cwd = process.cwd(), stacksRoot = cliStacksRoot()) {
+    return path.join(stacksRoot, stableRepoId(cwd));
+}
+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/stack-meta.d.ts

@@ -3,13 +3,31 @@ export type StackLayerMeta = {
     /** Parent branch name (trunk for the bottom layer). */
     parentBranch: string;
 };
+export type LocalStack = {
+    layers: StackLayerMeta[];
+};
 export type StackMeta = {
-    version: 1;
+    version: 2;
     trunk: string;
-    layers: StackLayerMeta[];
+    stacks: LocalStack[];
+    /** Index into `stacks` for create/submit. */
+    active: number;
 };
+/** Exported only for legacy migration/tests. New state never uses this path. */
 export declare const STACK_META_REL: string;
-export declare function stackMetaPath(cwd?: string): string;
-export declare function loadStackMeta(cwd?: string): Promise<StackMeta | null>;
-export declare function saveStackMeta(meta: StackMeta, cwd?: string): Promise<void>;
+export declare function stackMetaPath(cwd?: string, stacksRoot?: string): string;
+export declare function loadStackMeta(cwd?: string, stacksRoot?: string): Promise<StackMeta | null>;
+export declare function emptyStackMeta(trunk: string): StackMeta;
+export declare function activeStack(meta: StackMeta): LocalStack;
+export declare function activeLayers(meta: StackMeta): StackLayerMeta[];
+export declare function saveStackMeta(meta: StackMeta, cwd?: string, stacksRoot?: string): Promise<void>;
+/** Explicit recovery. Does not touch branches, PRs, or registered server stacks. */
+export declare function resetStackMeta(cwd?: string, stacksRoot?: string): Promise<void>;
 export declare function appendLayer(meta: StackMeta, layer: StackLayerMeta): StackMeta;
+/**
+ * Decide which local stack receives a new layer.
+ * Onto trunk with a non-empty active stack → start a fresh local stack.
+ */
+export declare function selectStackForCreate(meta: StackMeta, parentBranch: string): StackMeta;
+/** Drop the active stack after a successful submit. */
+export declare function removeActiveStack(meta: StackMeta): StackMeta;

package/dist/stack-meta.js

@@ -1,25 +1,78 @@
 /**
- * Local stack metadata for `mg stack create` / `submit`.
- * Stored at `.mergestorm/stack.json` in the repo root.
+ * CLI-owned pre-submit stack metadata for `mg stack create` / `submit`.
+ * Stored outside repositories under ~/.mergestorm/stacks/<repo-id>/.
  */
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { chmod, copyFile, mkdir, readFile, readdir, rename, rm, rmdir, unlink, writeFile, } from "node:fs/promises";
 import path from "node:path";
-export const STACK_META_REL = path.join(".mergestorm", "stack.json");
-export function stackMetaPath(cwd = process.cwd()) {
-    return path.join(cwd, STACK_META_REL);
-}
-export async function loadStackMeta(cwd = process.cwd()) {
-    try {
-        const raw = await readFile(stackMetaPath(cwd), "utf8");
-        const parsed = JSON.parse(raw);
-        if (!parsed ||
-            parsed.version !== 1 ||
-            typeof parsed.trunk !== "string" ||
-            !Array.isArray(parsed.layers) ||
-            !parsed.layers.every(l => typeof l.branch === 'string' && typeof l.parentBranch === 'string')) {
-            return null;
+import { CommandError } from "./errors.js";
+import { git } from "./git.js";
+import { cliStacksRoot, gitTopLevel, LEGACY_STACK_META_REL, legacyStackMetaPath, repoStateDir, stackMetaPath as resolveStackMetaPath, } from "./repo-identity.js";
+/** Exported only for legacy migration/tests. New state never uses this path. */
+export const STACK_META_REL = LEGACY_STACK_META_REL;
+export function stackMetaPath(cwd = process.cwd(), stacksRoot = cliStacksRoot()) {
+    return resolveStackMetaPath(cwd, stacksRoot);
+}
+function isLayer(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const layer = value;
+    return typeof layer.branch === "string" && typeof layer.parentBranch === "string";
+}
+function normalizeMeta(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const obj = raw;
+    if (typeof obj.trunk !== "string" || !obj.trunk.trim()) {
+        throw new Error("Stack authoring state has no trunk; run `mg stack reset --force` to clear it.");
+    }
+    if (obj.version === 2) {
+        if (!Array.isArray(obj.stacks) || obj.stacks.length === 0) {
+            throw new Error("Stack authoring state has no stacks; run `mg stack reset --force` to clear it.");
+        }
+        const stacks = [];
+        for (const stack of obj.stacks) {
+            if (!stack ||
+                typeof stack !== "object" ||
+                !Array.isArray(stack.layers) ||
+                !stack.layers.every(isLayer)) {
+                throw new Error("Stack authoring state has a malformed stack entry; run `mg stack reset --force` to clear it.");
+            }
+            stacks.push({ layers: stack.layers });
         }
-        return parsed;
+        const active = obj.active;
+        if (typeof active !== "number" ||
+            !Number.isInteger(active) ||
+            active < 0 ||
+            active >= stacks.length) {
+            throw new Error("Stack authoring state has an invalid active stack; run `mg stack reset --force` to clear it.");
+        }
+        return { version: 2, trunk: obj.trunk, stacks, active };
+    }
+    if (obj.version === 1) {
+        if (!Array.isArray(obj.layers) || !obj.layers.every(isLayer)) {
+            throw new Error("Stack authoring state has malformed legacy layers; run `mg stack reset --force` to clear it.");
+        }
+        return {
+            version: 2,
+            trunk: obj.trunk,
+            stacks: [{ layers: obj.layers }],
+            active: 0,
+        };
+    }
+    throw new Error("Stack authoring state has an unknown version; run `mg stack reset --force` to clear it.");
+}
+function parseStateJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new CommandError("Stack authoring state is not valid JSON; run `mg stack reset --force` to clear it.");
+    }
+}
+async function readIfExists(file) {
+    try {
+        return await readFile(file, "utf8");
     }
     catch (err) {
         const code = err?.code;
@@ -28,14 +81,196 @@ export async function loadStackMeta(cwd = process.cwd()) {
         throw err;
     }
 }
-export async function saveStackMeta(meta, cwd = process.cwd()) {
-    const file = stackMetaPath(cwd);
-    await mkdir(path.dirname(file), { recursive: true });
-    await writeFile(file, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+async function removeLegacyFile(file, cwd = process.cwd(), force = false) {
+    const top = gitTopLevel(cwd);
+    const rel = path.relative(top, file);
+    try {
+        git(["rm", "-f", "--", rel], top);
+    }
+    catch (err) {
+        // Fall back to a plain unlink only for untracked files; otherwise the
+        // index entry would remain after the worktree copy is gone.
+        if (git(["ls-files", "--", rel], top).trim() !== "") {
+            if (!force) {
+                throw new Error(`git rm failed for tracked ${rel}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            git(["update-index", "--force-remove", "--", rel], top);
+        }
+        await unlink(file);
+    }
+    try {
+        await rmdir(path.dirname(file));
+    }
+    catch {
+        // Leave a non-empty .mergestorm directory untouched.
+    }
+}
+export async function loadStackMeta(cwd = process.cwd(), stacksRoot = cliStacksRoot()) {
+    const file = stackMetaPath(cwd, stacksRoot);
+    const legacyFile = legacyStackMetaPath(cwd);
+    const raw = await readIfExists(file);
+    const legacyRaw = await readIfExists(legacyFile);
+    if (raw !== null) {
+        const meta = normalizeMeta(parseStateJson(raw));
+        if (meta === null) {
+            throw new CommandError("Stack authoring state is not an object; run `mg stack reset --force` to clear it.");
+        }
+        if (legacyRaw !== null) {
+            const stateDir = repoStateDir(cwd, stacksRoot);
+            const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+            const backup = path.join(stateDir, `legacy-conflict-${stamp}.json`);
+            try {
+                await mkdir(stateDir, { recursive: true, mode: 0o700 });
+                await chmod(stateDir, 0o700);
+                await copyFile(legacyFile, backup);
+                await chmod(backup, 0o600);
+                await removeLegacyFile(legacyFile, cwd);
+            }
+            catch (err) {
+                throw new CommandError(`Failed to preserve legacy stack state${err instanceof Error ? `: ${err.message}` : ""}; run \`mg stack reset --force\` to clear it.`);
+            }
+            console.warn(`Warning: global stack state already existed; preserved legacy state at ${backup}.`);
+        }
+        return meta;
+    }
+    if (legacyRaw === null)
+        return null;
+    const migrated = normalizeMeta(parseStateJson(legacyRaw));
+    if (!migrated)
+        return null;
+    try {
+        await saveStackMeta(migrated, cwd, stacksRoot);
+        await removeLegacyFile(legacyFile, cwd);
+    }
+    catch (err) {
+        throw new CommandError(`Failed to migrate legacy stack state${err instanceof Error ? `: ${err.message}` : ""}; run \`mg stack reset --force\` to clear it.`);
+    }
+    return migrated;
+}
+export function emptyStackMeta(trunk) {
+    return {
+        version: 2,
+        trunk,
+        stacks: [{ layers: [] }],
+        active: 0,
+    };
+}
+export function activeStack(meta) {
+    const stack = meta.stacks[meta.active];
+    if (!stack) {
+        throw new Error("Stack authoring state has an out-of-range active stack; run `mg stack reset --force` to clear it.");
+    }
+    return stack;
+}
+export function activeLayers(meta) {
+    return activeStack(meta).layers;
+}
+export async function saveStackMeta(meta, cwd = process.cwd(), stacksRoot = cliStacksRoot()) {
+    const file = stackMetaPath(cwd, stacksRoot);
+    const dir = path.dirname(file);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+    const base = path.basename(file);
+    for (const name of await readdir(dir)) {
+        if (name.startsWith(`${base}.`) && name.endsWith(".tmp")) {
+            await rm(path.join(dir, name), { force: true }).catch(() => { });
+        }
+    }
+    const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, `${JSON.stringify(meta, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        await rename(temp, file);
+        await chmod(file, 0o600);
+    }
+    catch (err) {
+        await rm(temp, { force: true }).catch(() => { });
+        throw err;
+    }
+}
+/** Explicit recovery. Does not touch branches, PRs, or registered server stacks. */
+export async function resetStackMeta(cwd = process.cwd(), stacksRoot = cliStacksRoot()) {
+    let stateFile;
+    let legacyFile;
+    try {
+        stateFile = stackMetaPath(cwd, stacksRoot);
+        legacyFile = legacyStackMetaPath(cwd);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== undefined)
+            throw err;
+        if (err instanceof Error &&
+            (err.message.includes("not a git repository") ||
+                err.message.includes("git common directory is missing"))) {
+            return;
+        }
+        throw err;
+    }
+    await rm(stateFile, { force: true });
+    try {
+        await removeLegacyFile(legacyFile, cwd, true);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
 }
 export function appendLayer(meta, layer) {
-    if (meta.layers.some((l) => l.branch === layer.branch)) {
+    const current = activeLayers(meta);
+    if (current.some((l) => l.branch === layer.branch)) {
         throw new Error(`branch already in stack: ${layer.branch}`);
     }
-    return { ...meta, layers: [...meta.layers, layer] };
+    for (let i = 0; i < meta.stacks.length; i++) {
+        if (i === meta.active)
+            continue;
+        if (meta.stacks[i].layers.some((l) => l.branch === layer.branch)) {
+            throw new Error(`branch already in another local stack: ${layer.branch}`);
+        }
+    }
+    const stacks = meta.stacks.map((stack, index) => index === meta.active
+        ? { layers: [...stack.layers, layer] }
+        : stack);
+    return { ...meta, stacks };
+}
+/**
+ * Decide which local stack receives a new layer.
+ * Onto trunk with a non-empty active stack → start a fresh local stack.
+ */
+export function selectStackForCreate(meta, parentBranch) {
+    const layers = activeLayers(meta);
+    if (parentBranch === meta.trunk) {
+        if (layers.length === 0)
+            return meta;
+        return {
+            ...meta,
+            stacks: [...meta.stacks, { layers: [] }],
+            active: meta.stacks.length,
+        };
+    }
+    if (layers.some((l) => l.branch === parentBranch)) {
+        return meta;
+    }
+    if (layers.length === 0) {
+        return meta;
+    }
+    for (let i = 0; i < meta.stacks.length; i++) {
+        if (meta.stacks[i].layers.some((l) => l.branch === parentBranch)) {
+            throw new Error(`Parent ${parentBranch} is a layer of a different local stack than the active one.`);
+        }
+    }
+    throw new Error(`Parent ${parentBranch} is not trunk (${meta.trunk}) or a stack layer.`);
+}
+/** Drop the active stack after a successful submit. */
+export function removeActiveStack(meta) {
+    if (meta.stacks.length <= 1) {
+        return { ...meta, stacks: [{ layers: [] }], active: 0 };
+    }
+    const stacks = meta.stacks.filter((_, index) => index !== meta.active);
+    const active = Math.min(meta.active, stacks.length - 1);
+    return { ...meta, stacks, active };
 }

package/dist/ui/banner.js

@@ -46,6 +46,14 @@ const WHATS_NEW = {
         "`stack submit` fills PR body from the tip commit (keeps Fixes/Closes)",
         "Unit-stack `stack land` promotes (matches server gates)",
     ],
+    "0.3.6": [
+        "Stack state under ~/.mergestorm/stacks/ (multi-stack + legacy migrate)",
+        "`stack reset --force` clears stale local authoring state",
+    ],
+    "0.3.7": [
+        "MIT license + public source at github.com/marginsystems/mergestorm-cli",
+        "npm repository/bugs point at the public CLI repo",
+    ],
 };
 function formatStatusLines(me, key, barWidth) {
     if (!key) {

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "mergestorm",
-  "version": "0.3.5",
-  "description": "MergeStorm CLI — interactive shell and one-shot review commands",
+  "version": "0.3.7",
+  "description": "Mergestorm CLI — interactive shell and one-shot review commands",
+  "license": "MIT",
   "type": "module",
   "bin": {
     "mergestorm": "./dist/cli.js",
@@ -10,14 +11,15 @@
   "homepage": "https://mergestorm.ai/docs#review-jobs-api",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/marginsystems/mergestorm.git",
-    "directory": "packages/mergestorm-cli"
+    "url": "git+https://github.com/marginsystems/mergestorm-cli.git"
   },
   "bugs": {
-    "url": "https://github.com/marginsystems/mergestorm/issues"
+    "url": "https://github.com/marginsystems/mergestorm-cli/issues"
   },
   "files": [
-    "dist"
+    "dist",
+    "LICENSE",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",