gh-stack 0.4.0 → 0.7.0

package/README.md

@@ -83,6 +83,13 @@ submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file
     that don't have them, and update all PR descriptions with stack
     visualization. Idempotent — safe to run repeatedly.
 
+    Self-healing: if the current branch isn't tracked in a stack yet,
+    submit auto-detects the chain from trunk → current, registers (or
+    reconciles into) a stack, then pushes + creates PRs for the whole
+    chain. You never need to run `gh-stack init` first — running submit
+    from the top of a bare chain of local branches converges to the
+    expected end state (stack registered, branches pushed, PRs created).
+
     --title/-t and --body/-b provide PR details directly (skips prompts).
     --body-file reads body from a file. In --yes mode without --title,
     auto-generates PR titles from branch names.
@@ -131,12 +138,16 @@ sync [--dry-run]
     children. Snapshots every branch's pre-sync tip so children can be
     correctly rebased even though their parent's history was rewritten.
 
-merge [--dry-run] [-d|--delete-branch]
+merge [--dry-run] [-d|--delete-branch] [--collapse]
     Squash-merge the stack top-down via GitHub (PR3 → PR2 → PR1),
     then enables auto-merge for the base PR into main. All merges
     happen on GitHub so PRs show as "Merged", Linear tickets close
     automatically, and GitHub Actions fire normally. Skips already-
     merged PRs (safe to re-run). Waits for GitHub between merges.
+    --collapse  Stop after collapsing the stack into the base PR;
+                leaves the base PR open against main so you can
+                review the cumulative diff on GitHub. Re-run
+                `gh-stack merge` (without --collapse) to finish.
 
 delete [<branch>]
     Remove a branch from the stack and re-parent its children.
@@ -166,14 +177,18 @@ archive [--restore <name>]
 
 ```
 --yes, -y      Skip all confirmations (for agents/CI)
+--plain        Plain output — no spinners, colors, or banner boxes
 --help         Show help for a command
 --version, -V  Show version
 ```
 
+`--plain` is auto-enabled when `--yes` / `GH_STACK_YES=1` is set, so agents get clean, easily-filtered output by default. Use `--plain` alone if you want plain output but still interactive prompts.
+
 ## Environment Variables
 
 ```
-GH_STACK_YES=1         Skip all confirmations (same as --yes)
+GH_STACK_YES=1         Skip all confirmations (same as --yes; also enables --plain)
+GH_STACK_PLAIN=1       Plain output (same as --plain)
 GH_STACK_NO_COLOR=1    Disable colored output
 ```
 
@@ -262,6 +277,11 @@ gh-stack status
 
 # When PRs are approved, merge the stack
 gh-stack merge       # squash-merges down, pushes, enables auto-merge
+
+# Or: collapse first to review the cumulative diff before shipping
+gh-stack merge --collapse   # squash-merges PRn..PR2 into PR1, stops there
+# ...review base PR on GitHub...
+gh-stack merge              # finishes base PR → main + archives the stack
 ```
 
 ## Agent/CI Usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gh-stack",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",

package/src/commands/archive.ts

@@ -1,5 +1,5 @@
 // gh-stack archive — Manage archived stacks
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { writeMetadata } from "../lib/metadata.ts";
 import { ensureMetadata } from "../lib/safety.ts";

package/src/commands/bottom.ts

@@ -1,5 +1,5 @@
 // gh-stack bottom — Jump to the base of the stack
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, getOrderedBranches, writeMetadata } from "../lib/metadata.ts";

package/src/commands/checkout.ts

@@ -1,5 +1,5 @@
 // gh-stack checkout — Switch between branches or stacks
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { writeMetadata, getOrderedBranches, findStackForBranch } from "../lib/metadata.ts";

package/src/commands/create.ts

@@ -1,5 +1,5 @@
 // gh-stack create — Create a new branch and add to the stack
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, addBranchToStack } from "../lib/metadata.ts";

package/src/commands/delete.ts

@@ -1,5 +1,5 @@
 // gh-stack delete — Delete a branch from the stack (re-link parent chain)
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { removeBranchFromStack, getChildren } from "../lib/metadata.ts";
 import { ensureMetadata, ensureCurrentStack, ensureValidStack } from "../lib/safety.ts";

package/src/commands/down.ts

@@ -1,5 +1,5 @@
 // gh-stack down — Move to parent branch (downstack)
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, writeMetadata } from "../lib/metadata.ts";

package/src/commands/init.ts

@@ -1,5 +1,5 @@
 // gh-stack init — Create a new stack, auto-detecting branch chains
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import {
@@ -12,6 +12,7 @@ import {
 } from "../lib/metadata.ts";
 import { getPrNumber } from "../lib/github.ts";
 import { isAutoYes } from "../lib/ui.ts";
+import { detectBranchChain } from "../lib/chain.ts";
 import type { StackMetadata, Branch } from "../types.ts";
 
 const HELP = `
@@ -37,50 +38,6 @@ EXAMPLES
   gh-stack init --parent develop             # Different trunk branch
 `;
 
-/**
- * Detect a chain of branches from trunk to the current branch.
- *
- * Walks down from the current branch by finding local branches whose
- * tips are strict ancestors of the current branch. Sorts by commit
- * distance (closest = direct parent) to reconstruct the chain.
- *
- * Returns branches in bottom-up order: [closest-to-trunk, ..., current]
- */
-async function detectBranchChain(currentBranch: string, trunk: string): Promise<string[]> {
-  const allBranches = await git.allLocalBranches();
-
-  // Branches to exclude: current, trunk, and always main/master
-  const excluded = new Set([currentBranch, trunk, "main", "master"]);
-
-  // Find branches that are strict ancestors of current (and not trunk)
-  const ancestors: { name: string; distance: number }[] = [];
-
-  for (const branch of allBranches) {
-    if (excluded.has(branch)) continue;
-
-    // Is this branch's tip an ancestor of current?
-    if (await git.isAncestor(branch, currentBranch)) {
-      // Skip branches already merged into trunk (stale/old branches)
-      if (await git.isAncestor(branch, trunk)) continue;
-
-      // How many commits between this branch and current?
-      const distance = await git.commitCount(branch, currentBranch);
-      if (distance > 0) {
-        ancestors.push({ name: branch, distance });
-      }
-    }
-  }
-
-  // Sort by distance descending (furthest from current = closest to trunk)
-  ancestors.sort((a, b) => b.distance - a.distance);
-
-  // Build chain: ancestors (sorted trunk→current) + current branch
-  const chain = ancestors.map((a) => a.name);
-  chain.push(currentBranch);
-
-  return chain;
-}
-
 export default async function init(args: string[]): Promise<void> {
   // Parse flags
   let nameFlag: string | undefined;

package/src/commands/log.ts

@@ -1,5 +1,5 @@
 // gh-stack log — Display current stack tree (default command)
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import {

package/src/commands/merge.ts

@@ -1,5 +1,5 @@
 // gh-stack merge — Squash-merge stack top-down via GitHub
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { $ } from "bun";
 import * as git from "../lib/git.ts";
@@ -41,13 +41,14 @@ async function waitForMergeable(
 export default async function merge(args: string[]): Promise<void> {
   const dryRun = args.includes("--dry-run");
   const deleteFlag = args.includes("--delete-branch") || args.includes("-d");
+  const collapse = args.includes("--collapse") || args.includes("--stop-at-base");
 
   if (args.includes("--help")) {
     console.log(`
 gh-stack merge — Squash-merge stack via GitHub
 
 USAGE
-  gh-stack merge [--dry-run] [-d|--delete-branch]
+  gh-stack merge [--dry-run] [-d|--delete-branch] [--collapse]
 
 Squash-merges the stack from top to bottom via GitHub:
   PR3 → squash into PR2, PR2 → squash into PR1, PR1 → auto-merge into main.
@@ -61,6 +62,11 @@ Waits for GitHub to process between merges if needed.
 OPTIONS
   -d, --delete-branch  Delete remote branches after merging
       --dry-run        Show what would happen without doing anything
+      --collapse       Stop after collapsing the stack into the base PR;
+                       do NOT merge base PR into main. Lets you review the
+                       cumulative diff on GitHub first. Re-run ${pc.green("gh-stack merge")}
+                       (without --collapse) to finish the job.
+      --stop-at-base   Alias for --collapse
 `);
     return;
   }
@@ -81,6 +87,12 @@ OPTIONS
   if (ordered.length <= 1) {
     // Single branch — just enable auto-merge
     const basePr = stack.branches[ordered[0]!]?.pr;
+    if (collapse) {
+      p.log.info(
+        `Single-branch stack — nothing to collapse. The base PR${basePr ? ` (#${basePr})` : ""} already targets main.`,
+      );
+      return;
+    }
     if (basePr) {
       p.log.info("Single branch stack — enabling auto-merge on GitHub.");
       if (!dryRun) {
@@ -97,8 +109,13 @@ OPTIONS
     return;
   }
 
-  p.intro(pc.cyan("Stack Merge (via GitHub)"));
+  p.intro(pc.cyan(collapse ? "Stack Collapse (via GitHub)" : "Stack Merge (via GitHub)"));
   p.log.info(`Stack: ${pc.yellow(stackName)}`);
+  if (collapse) {
+    p.log.info(
+      pc.dim("--collapse: will stop after collapsing into base PR; base will NOT merge to main."),
+    );
+  }
   console.log();
 
   // Check PR states and build the merge plan
@@ -121,9 +138,15 @@ OPTIONS
       `    ${pc.yellow(child)}${childPr ? ` (#${childPr})` : ""} → squash into ${pc.blue(parent)}${mergedLabel}`,
     );
   }
-  console.log(
-    `    ${pc.blue(baseBranch)}${basePr ? ` (#${basePr})` : ""} → ${pc.green("main")} (auto-merge)`,
-  );
+  if (collapse) {
+    console.log(
+      `    ${pc.blue(baseBranch)}${basePr ? ` (#${basePr})` : ""} → ${pc.dim("(stop — review on GitHub, then re-run merge to finish)")}`,
+    );
+  } else {
+    console.log(
+      `    ${pc.blue(baseBranch)}${basePr ? ` (#${basePr})` : ""} → ${pc.green("main")} (auto-merge)`,
+    );
+  }
   console.log();
 
   if (dryRun) {
@@ -140,14 +163,18 @@ OPTIONS
     process.exit(1);
   }
 
-  const confirmed = await confirmAction("Squash-merge stack top-down via GitHub?");
+  const confirmed = await confirmAction(
+    collapse
+      ? "Collapse stack top-down via GitHub (stop at base PR)?"
+      : "Squash-merge stack top-down via GitHub?",
+  );
   if (!confirmed) {
     p.cancel("Cancelled");
     process.exit(0);
   }
 
   // Take snapshot
-  await takeSnapshot(meta, stackName, "merge");
+  await takeSnapshot(meta, stackName, collapse ? "collapse" : "merge");
 
   // Merge top-down via GitHub: for each PR from top, squash-merge into parent
   for (let i = 0; i < reversed.length - 1; i++) {
@@ -205,6 +232,74 @@ OPTIONS
     }
   }
 
+  // ─── --collapse: stop here. Base PR holds the cumulative diff; let the
+  //     user review on GitHub and re-run `gh-stack merge` to finish.
+  if (collapse) {
+    console.log();
+
+    // Park the user on the base branch — mirrors how normal merge lands you
+    // on `main`. Fetch origin so they can see how far behind their local
+    // base branch is (the squashed commits live only on origin/<base> now).
+    const checkoutSpinner = p.spinner();
+    checkoutSpinner.start(`Checking out base branch ${pc.yellow(baseBranch)}...`);
+    let localBehind = false;
+    try {
+      await $`git fetch origin`.quiet();
+      await git.checkout(baseBranch);
+
+      // Compare local vs origin to flag the user if their local base is stale
+      try {
+        const localSha = await git.revParse(baseBranch);
+        const remoteSha = await git.revParse(`origin/${baseBranch}`);
+        localBehind = localSha !== remoteSha;
+      } catch {}
+
+      checkoutSpinner.stop(`On base branch ${pc.yellow(baseBranch)}`);
+    } catch {
+      checkoutSpinner.stop(pc.dim(`Could not checkout ${baseBranch} — switch manually if needed`));
+    }
+
+    console.log();
+    console.log(pc.cyan("━".repeat(40)));
+    console.log(pc.green("  Stack collapsed into base PR"));
+    console.log(pc.cyan("━".repeat(40)));
+    console.log();
+
+    // Fetch the base PR URL for a clickable summary line
+    let baseUrl: string | null = null;
+    try {
+      const proc = Bun.spawn(["gh", "pr", "view", String(basePr), "--json", "url", "-q", ".url"], {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const out = (await new Response(proc.stdout).text()).trim();
+      if ((await proc.exited) === 0 && out) baseUrl = out;
+    } catch {}
+
+    console.log(
+      `  ${pc.blue("Base PR:")} #${basePr} ${pc.yellow(baseBranch)} → ${pc.green("main")}`,
+    );
+    if (baseUrl) console.log(`  ${pc.dim(baseUrl)}`);
+    if (localBehind) {
+      console.log();
+      console.log(
+        `  ${pc.yellow("⚠")} Local ${pc.yellow(baseBranch)} is behind ${pc.dim(`origin/${baseBranch}`)}`,
+      );
+      console.log(
+        `    ${pc.dim("(squashed commits from upper PRs live on origin only — review the diff on GitHub)")}`,
+      );
+    }
+    console.log();
+    console.log(`  ${pc.dim("Review the cumulative diff on GitHub. When ready to ship:")}`);
+    console.log(
+      `    ${pc.green("gh-stack merge")}    ${pc.dim("# finishes base PR → main + archives")}`,
+    );
+    console.log();
+
+    p.outro(pc.green("Collapse complete — stack left intact for review."));
+    return;
+  }
+
   // Base PR → enable auto-merge into main
   console.log();
   console.log(pc.cyan("━".repeat(40)));

package/src/commands/restack.ts

@@ -1,6 +1,6 @@
 // gh-stack restack — Rebase children onto updated parents
 // Port of reference/gh-stack-sync.sh — the most critical command
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import {
@@ -281,16 +281,21 @@ async function processChain(
     //
     //   Strategy:
     //     1. Look for a recent snapshot where the parent's recorded tip is no
-    //        longer an ancestor of the parent's current tip. That recorded SHA
-    //        is the orphaned old-parent tip — exactly the rebase base we need.
+    //        longer an ancestor of the parent's current tip AND is still an
+    //        ancestor of the child. That recorded SHA is the orphaned
+    //        old-parent tip — exactly the rebase base we need.
     //     2. Fall back to `merge-base(branch, parent)` if no snapshot tells us
     //        the parent was rewritten (typical case: parent only had commits
     //        appended, not rebased).
     //
+    //   The child-ancestry check (issue #5) prevents stale snapshots from
+    //   older sessions — where the child has already been rebased past the
+    //   recorded point — from being used as a rebase base.
+    //
     //   Re-read metadata fresh because previous iterations of this loop may
     //   have updated snapshots.
     const freshMeta = (await readMetadata()) ?? meta;
-    const oldBaseFromSnapshot = await findPreRewriteSha(freshMeta, parent);
+    const oldBaseFromSnapshot = await findPreRewriteSha(freshMeta, parent, branch);
     const oldBaseFromMergeBase = await git.mergeBase(branch, parent);
     const oldBase = oldBaseFromSnapshot ?? oldBaseFromMergeBase;
 

package/src/commands/submit.ts

@@ -1,12 +1,18 @@
 // gh-stack submit — Push branches and create/update PRs
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import { $ } from "bun";
 import * as git from "../lib/git.ts";
-import { findStackForBranch, getOrderedBranches, writeMetadata } from "../lib/metadata.ts";
-import { ensureMetadata } from "../lib/safety.ts";
+import {
+  findStackForBranch,
+  getOrderedBranches,
+  readMetadata,
+  writeMetadata,
+} from "../lib/metadata.ts";
 import { isAutoYes } from "../lib/ui.ts";
+import type { StackMetadata } from "../types.ts";
 import { getPrNumber, getPrInfo, getPrBody, updatePrBody, reviewEmoji } from "../lib/github.ts";
+import { resolveOrCreateStack } from "../lib/chain.ts";
 import { buildStackViz } from "./update-prs.ts";
 
 const HELP = `
@@ -19,6 +25,11 @@ Pushes all branches from trunk to the current branch, creating PRs
 for branches that don't have them and updating stack visualization
 in all PR descriptions. Idempotent — safe to run repeatedly.
 
+Self-healing: if the current branch isn't tracked in a stack yet,
+submit auto-detects the branch chain from trunk → current, registers
+(or reconciles into) a stack, then pushes + creates PRs for the whole
+chain. You never need to run \`gh-stack init\` first.
+
 OPTIONS
   -d, --draft          Create new PRs as drafts
   -n, --no-edit        Don't prompt for PR titles (auto-generate from branch name)
@@ -110,13 +121,50 @@ export default async function submit(args: string[]): Promise<void> {
 
   const noEdit = args.includes("--no-edit") || args.includes("-n") || isAutoYes() || !!titleFlag;
 
-  const meta = await ensureMetadata();
+  // Read metadata, or start with an empty in-memory store. submit self-heals,
+  // so a missing metadata file is fine — we'll build the stack from local
+  // branch ancestry and persist it (unless --dry-run).
+  const meta: StackMetadata = (await readMetadata()) ?? {
+    version: 2,
+    current_stack: null,
+    stacks: {},
+  };
   const branch = await git.currentBranch();
-  const stackName = findStackForBranch(meta, branch);
+  let stackName = findStackForBranch(meta, branch);
 
+  // ── Self-heal: branch isn't in any stack ──
+  // Reconstruct the stack from local branch ancestry so the end state is
+  // always stack registered + branches pushed + PRs created — no need to
+  // remember to run `gh-stack init` first.
+  let heal: { trunk: string; chain: string[]; created: boolean; added: string[] } | null = null;
   if (!stackName) {
-    p.cancel(`Branch ${pc.blue(branch)} not found in any stack`);
-    process.exit(1);
+    const trunk = await git.trunkBranch();
+
+    if (branch === trunk || branch === "main" || branch === "master") {
+      p.cancel(
+        `You're on ${pc.blue(branch)} — nothing to submit.\n\n  Checkout a feature branch first.`,
+      );
+      process.exit(1);
+    }
+
+    let resolution;
+    try {
+      resolution = await resolveOrCreateStack(meta, branch, trunk);
+    } catch (err) {
+      p.cancel((err as Error).message);
+      process.exit(1);
+    }
+
+    stackName = resolution.stackName;
+    heal = {
+      trunk,
+      chain: resolution.chain,
+      created: resolution.created,
+      added: resolution.addedBranches,
+    };
+
+    // Persist the reconstructed/updated stack before pushing (skip on dry-run)
+    if (!dryRun) await writeMetadata(meta);
   }
 
   const stack = meta.stacks[stackName]!;
@@ -127,6 +175,34 @@ export default async function submit(args: string[]): Promise<void> {
   const scope = currentIndex >= 0 ? ordered.slice(0, currentIndex + 1) : ordered;
 
   p.intro(pc.cyan("Submit Stack"));
+
+  // Report self-heal results (stack creation / reconciliation + detected chain)
+  if (heal) {
+    if (heal.created) {
+      p.log.success(
+        `No stack found — created ${pc.yellow(stackName)} from ${heal.chain.length} local branch(es)`,
+      );
+    } else if (heal.added.length > 0) {
+      p.log.success(
+        `Reconciled ${heal.added.length} untracked branch(es) into ${pc.yellow(stackName)}`,
+      );
+    }
+
+    console.log();
+    console.log(`  ${pc.dim(heal.trunk)}`);
+    for (let i = 0; i < heal.chain.length; i++) {
+      const b = heal.chain[i]!;
+      const isLast = i === heal.chain.length - 1;
+      const tree = isLast ? "  ┗━" : "  ┣━";
+      const isNew = heal.added.includes(b);
+      const label = b === branch ? pc.yellow(b) + pc.dim(" (current)") : b;
+      const tag = isNew ? pc.green(" +") : "";
+      console.log(`${tree} ${label}${tag}`);
+      if (!isLast) console.log("  ┃");
+    }
+    console.log();
+  }
+
   p.log.info(`Stack: ${pc.yellow(stackName)}`);
   p.log.info(
     `Scope: ${scope.length} of ${ordered.length} branch(es) (downstack from ${pc.blue(branch)})`,

package/src/commands/sync.ts

@@ -1,5 +1,5 @@
 // gh-stack sync — Fetch main, rebase base branch onto main, then restack all
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, getOrderedBranches, saveRestackState } from "../lib/metadata.ts";

package/src/commands/top.ts

@@ -1,5 +1,5 @@
 // gh-stack top — Jump to the tip of the stack
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import {

package/src/commands/undo.ts

@@ -1,5 +1,5 @@
 // gh-stack undo — Restore from last snapshot
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import * as git from "../lib/git.ts";
 import pc from "picocolors";
 import { ensureMetadata, ensureCleanWorkingTree } from "../lib/safety.ts";

package/src/commands/up.ts

@@ -1,5 +1,5 @@
 // gh-stack up — Move to child branch (upstack)
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, getChildren, writeMetadata } from "../lib/metadata.ts";

package/src/commands/update-prs.ts

@@ -1,6 +1,6 @@
 // gh-stack update-prs — Update PR descriptions with stack visualization
 // Port of reference/gh-stack-update-pr.sh
-import * as p from "@clack/prompts";
+import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, getOrderedBranches } from "../lib/metadata.ts";

package/src/index.ts

@@ -1,14 +1,23 @@
 #!/usr/bin/env bun
 // gh-stack — Unified stacked PR manager for squash-merge workflows
 
-// Map GH_STACK_NO_COLOR → NO_COLOR so picocolors (and other tools) respect it
-if (process.env.GH_STACK_NO_COLOR) {
+// Map GH_STACK_NO_COLOR → NO_COLOR so picocolors (and other tools) respect it.
+// Also pre-detect plain mode (--plain flag, GH_STACK_YES=1, or GH_STACK_PLAIN=1)
+// and set NO_COLOR *before* any import below — picocolors snapshots env at
+// load time, so this must run before the import block.
+const _earlyArgs = process.argv.slice(2);
+const _earlyPlain =
+  _earlyArgs.includes("--plain") ||
+  process.env.GH_STACK_YES === "1" ||
+  process.env.GH_STACK_PLAIN === "1";
+if (process.env.GH_STACK_NO_COLOR || _earlyPlain) {
   process.env.NO_COLOR = "1";
 }
 
 import { ensureGitRepo } from "./lib/safety.ts";
 import { parseCliArgs } from "./lib/cli.ts";
 import { setAutoYes } from "./lib/ui.ts";
+import { setPlain } from "./lib/output.ts";
 
 const { version: VERSION } = await import("../package.json");
 
@@ -32,6 +41,11 @@ if (parsed.autoYes) {
   setAutoYes(true);
 }
 
+// Global --plain (or GH_STACK_YES=1): drop intro/outro/spinner/color chrome.
+if (parsed.plain) {
+  setPlain(true);
+}
+
 // Ensure we're in a git repo for all commands
 await ensureGitRepo();
 
@@ -160,11 +174,13 @@ ${bold("INFO & MAINTENANCE")}
 
 ${bold("GLOBAL OPTIONS")}
   --yes, -y        Skip confirmations ${dim("(for agents/CI)")}
+  --plain          Plain output: no spinners, colors, or box drawing
   --help           Show help
   --version, -V    Show version
 
 ${bold("ENVIRONMENT")}
-  GH_STACK_YES=1       Same as --yes
+  GH_STACK_YES=1       Same as --yes (also enables --plain)
+  GH_STACK_PLAIN=1     Same as --plain
   GH_STACK_NO_COLOR    Disable colored output
 `);
 }

package/src/lib/chain.ts

@@ -0,0 +1,140 @@
+// Branch-chain detection and stack reconciliation.
+//
+// Shared by `init` (interactive stack creation) and `submit` (self-healing:
+// auto-create/register a stack from a bare set of local branches so the
+// end state is always stack registered + branches pushed + PRs created).
+import * as git from "./git.ts";
+import { findStackForBranch } from "./metadata.ts";
+import type { StackMetadata, Branch } from "../types.ts";
+
+/**
+ * Detect a chain of branches from trunk to the current branch.
+ *
+ * Walks down from the current branch by finding local branches whose tips
+ * are strict ancestors of the current branch. Sorts by commit distance
+ * (closest = direct parent) to reconstruct the chain. Branches already
+ * merged into trunk are skipped (stale/old branches).
+ *
+ * Returns branches in bottom-up order: [closest-to-trunk, ..., current].
+ * For a branch based directly off trunk, returns just [current].
+ */
+export async function detectBranchChain(currentBranch: string, trunk: string): Promise<string[]> {
+  const allBranches = await git.allLocalBranches();
+
+  // Branches to exclude: current, trunk, and always main/master
+  const excluded = new Set([currentBranch, trunk, "main", "master"]);
+
+  // Find branches that are strict ancestors of current (and not trunk)
+  const ancestors: { name: string; distance: number }[] = [];
+
+  for (const branch of allBranches) {
+    if (excluded.has(branch)) continue;
+
+    // Is this branch's tip an ancestor of current?
+    if (await git.isAncestor(branch, currentBranch)) {
+      // Skip branches already merged into trunk (stale/old branches)
+      if (await git.isAncestor(branch, trunk)) continue;
+
+      // How many commits between this branch and current?
+      const distance = await git.commitCount(branch, currentBranch);
+      if (distance > 0) {
+        ancestors.push({ name: branch, distance });
+      }
+    }
+  }
+
+  // Sort by distance descending (furthest from current = closest to trunk)
+  ancestors.sort((a, b) => b.distance - a.distance);
+
+  // Build chain: ancestors (sorted trunk→current) + current branch
+  const chain = ancestors.map((a) => a.name);
+  chain.push(currentBranch);
+
+  return chain;
+}
+
+export interface StackResolution {
+  stackName: string;
+  chain: string[]; // trunk→current order
+  created: boolean; // true if a brand-new stack was created
+  addedBranches: string[]; // branches newly registered into the stack
+}
+
+/**
+ * Ensure a stack exists for `branch`, reconstructing it from local branch
+ * ancestry if needed. Mutates `meta` in place but does NOT persist — the
+ * caller decides when to write (so `--dry-run` can preview without side
+ * effects).
+ *
+ * Behavior:
+ *   - Detects the chain trunk→current.
+ *   - If any branch in the chain already belongs to a stack, reconciles
+ *     into that existing stack (adds only the missing branches).
+ *   - Otherwise creates a new stack named after the current branch
+ *     (auto-suffixed if that name is taken).
+ *   - Registers missing branches with correct parent links (chain[0]'s
+ *     parent is trunk; each subsequent branch's parent is the prior one).
+ *
+ * Throws if the chain spans more than one existing stack (ambiguous).
+ */
+export async function resolveOrCreateStack(
+  meta: StackMetadata,
+  branch: string,
+  trunk: string,
+): Promise<StackResolution> {
+  const chain = await detectBranchChain(branch, trunk);
+
+  // Which existing stacks (if any) already own branches in this chain?
+  const owningStacks = new Set<string>();
+  for (const b of chain) {
+    const owner = findStackForBranch(meta, b);
+    if (owner) owningStacks.add(owner);
+  }
+
+  if (owningStacks.size > 1) {
+    throw new Error(
+      `Branches in this chain span multiple stacks (${[...owningStacks].join(
+        ", ",
+      )}). Resolve manually with gh-stack init / delete.`,
+    );
+  }
+
+  let stackName: string;
+  let created = false;
+
+  if (owningStacks.size === 1) {
+    // Reconcile into the existing stack
+    stackName = [...owningStacks][0]!;
+  } else {
+    // Create a new stack named after the current branch (auto-suffix on clash)
+    stackName = branch;
+    let n = 2;
+    while (meta.stacks[stackName]) {
+      stackName = `${branch}-${n++}`;
+    }
+    meta.stacks[stackName] = {
+      description: "",
+      last_branch: null,
+      branches: {},
+    };
+    meta.current_stack = stackName;
+    created = true;
+  }
+
+  const stack = meta.stacks[stackName]!;
+  const addedBranches: string[] = [];
+
+  // Register missing branches with correct parent links.
+  for (let i = 0; i < chain.length; i++) {
+    const name = chain[i]!;
+    if (stack.branches[name]) continue; // already tracked — leave as-is
+
+    const parent = i === 0 ? trunk : chain[i - 1]!;
+    const branchData: Branch = { parent };
+    stack.branches[name] = branchData;
+    stack.last_branch = name;
+    addedBranches.push(name);
+  }
+
+  return { stackName, chain, created, addedBranches };
+}

package/src/lib/cli.ts

@@ -2,11 +2,12 @@ export interface ParsedCliArgs {
   command: string;
   commandArgs: string[];
   autoYes: boolean;
+  plain: boolean;
   showVersion: boolean;
   showGlobalHelp: boolean;
 }
 
-const LEADING_GLOBAL_FLAGS = new Set(["--yes", "-y", "--help", "--version", "-V"]);
+const LEADING_GLOBAL_FLAGS = new Set(["--yes", "-y", "--plain", "--help", "--version", "-V"]);
 
 export function parseCliArgs(rawArgs: string[], env: NodeJS.ProcessEnv): ParsedCliArgs {
   let commandIndex = 0;
@@ -20,12 +21,18 @@ export function parseCliArgs(rawArgs: string[], env: NodeJS.ProcessEnv): ParsedC
   const command = rawArgs[commandIndex] || "log";
   const commandArgs = rawArgs
     .slice(commandIndex + 1)
-    .filter((arg) => arg !== "--yes" && arg !== "-y");
+    .filter((arg) => arg !== "--yes" && arg !== "-y" && arg !== "--plain");
+
+  const autoYes = rawArgs.includes("--yes") || rawArgs.includes("-y") || env.GH_STACK_YES === "1";
+  // Plain mode auto-enables under GH_STACK_YES=1 (agents skip the chrome anyway)
+  // or explicit --plain. Both compose with each other.
+  const plain = autoYes || rawArgs.includes("--plain") || env.GH_STACK_PLAIN === "1";
 
   return {
     command,
     commandArgs,
-    autoYes: rawArgs.includes("--yes") || rawArgs.includes("-y") || env.GH_STACK_YES === "1",
+    autoYes,
+    plain,
     showVersion: leadingFlags.has("--version") || leadingFlags.has("-V"),
     showGlobalHelp: !rawArgs[commandIndex] && leadingFlags.has("--help"),
   };

package/src/lib/git.ts

@@ -254,6 +254,16 @@ export async function allLocalBranches(): Promise<string[]> {
   return result.trim().split("\n").filter(Boolean);
 }
 
+/**
+ * Determine the trunk branch name. Prefers "main", falls back to "master"
+ * if only that exists locally. Defaults to "main" when neither is present.
+ */
+export async function trunkBranch(): Promise<string> {
+  if (await localBranchExists("main")) return "main";
+  if (await localBranchExists("master")) return "master";
+  return "main";
+}
+
 /**
  * Build a deterministic temp tag name for a branch.
  * Includes a readable slug plus a stable hash to avoid collisions.

package/src/lib/output.ts

@@ -0,0 +1,90 @@
+// Plain-mode-aware wrapper over @clack/prompts.
+//
+// In plain mode (--plain flag or GH_STACK_YES=1), we strip the decorative
+// chrome that makes gh-stack output painful for agents/log consumers:
+//   - no intro/outro boxes
+//   - no spinners (start/stop lines collapse to plain prints)
+//   - no ANSI colors (picocolors auto-disables via NO_COLOR; we also strip
+//     any residual escapes defensively)
+//
+// Interactive prompts (text, confirm, select) are re-exported unchanged —
+// plain mode is about output, not interactivity. Agents already pair --plain
+// with --yes/GH_STACK_YES so the interactive paths aren't reached.
+import * as clack from "@clack/prompts";
+
+let _plain = false;
+
+export function setPlain(enabled: boolean): void {
+  _plain = enabled;
+}
+
+export function isPlain(): boolean {
+  return _plain;
+}
+
+const ANSI_RE = new RegExp(String.fromCharCode(27) + "\\[[0-9;]*m", "g");
+function strip(s: string | undefined): string {
+  return (s ?? "").replace(ANSI_RE, "");
+}
+
+// ── Interactive prompts (unchanged) ──
+export const isCancel = clack.isCancel;
+export const text = clack.text;
+export const confirm = clack.confirm;
+export const select = clack.select;
+
+// ── Banner / error ──
+export function intro(message?: string): void {
+  if (_plain) {
+    if (message) console.log(strip(message));
+  } else {
+    clack.intro(message);
+  }
+}
+
+export function outro(message?: string): void {
+  if (_plain) {
+    if (message) console.log(strip(message));
+  } else {
+    clack.outro(message);
+  }
+}
+
+export function cancel(message?: string): void {
+  if (_plain) {
+    if (message) console.error(strip(message));
+  } else {
+    clack.cancel(message);
+  }
+}
+
+// ── log.* ──
+export const log = {
+  info: (msg: string) => (_plain ? console.log(strip(msg)) : clack.log.info(msg)),
+  success: (msg: string) => (_plain ? console.log(strip(msg)) : clack.log.success(msg)),
+  warn: (msg: string) => (_plain ? console.warn(strip(msg)) : clack.log.warn(msg)),
+  error: (msg: string) => (_plain ? console.error(strip(msg)) : clack.log.error(msg)),
+  step: (msg: string) => (_plain ? console.log(strip(msg)) : clack.log.step(msg)),
+};
+
+// ── Spinner ──
+export interface Spinner {
+  start: (msg?: string) => void;
+  stop: (msg?: string, code?: number) => void;
+  message: (msg?: string) => void;
+}
+
+export function spinner(): Spinner {
+  if (!_plain) return clack.spinner() as Spinner;
+  return {
+    start: (msg) => {
+      if (msg) console.log(strip(msg));
+    },
+    stop: (msg) => {
+      if (msg) console.log(strip(msg));
+    },
+    message: (msg) => {
+      if (msg) console.log(strip(msg));
+    },
+  };
+}

package/src/lib/safety.ts

@@ -2,7 +2,7 @@
 import * as git from "./git.ts";
 import { metadataExists, readMetadata, findStackForBranch } from "./metadata.ts";
 import type { StackMetadata, Stack } from "../types.ts";
-import * as p from "@clack/prompts";
+import * as p from "./output.ts";
 import pc from "picocolors";
 
 /**

package/src/lib/snapshot.ts

@@ -4,47 +4,73 @@ import * as git from "./git.ts";
 import { writeMetadata, getOrderedBranches } from "./metadata.ts";
 
 /**
- * Find the pre-rewrite SHA for a branch by walking snapshots newest-first.
+ * Find the pre-rewrite SHA for a parent branch by walking snapshots newest-first.
  *
  * Returns the SHA from the most recent snapshot whose recorded tip for
- * `branchName` is NOT an ancestor of the branch's current tip — meaning
- * that snapshot was taken before the branch's history got rewritten
+ * `parentBranch` is NOT an ancestor of the parent's current tip — meaning
+ * that snapshot was taken before the parent's history got rewritten
  * (typically by `sync` rebasing it onto a new main).
  *
  * That pre-rewrite SHA is the correct rebase base when restacking a child
- * onto this branch — `git rebase --onto <new-tip> <pre-rewrite-tip> <child>`
+ * onto this parent — `git rebase --onto <new-tip> <pre-rewrite-tip> <child>`
  * replays only the child's unique commits, never the parent's old history.
  *
- * Returns null if no snapshots exist or every snapshot's recorded tip is
- * still an ancestor of the current tip (i.e., the branch has only had
- * commits appended, never been rebased — `merge-base` is still correct).
+ * **Child validation (issue #5)**: When `childBranch` is provided, any candidate
+ * SHA must also still be an ancestor of the child. If the child has already
+ * been rebased past this point (e.g., a previous restack already moved it),
+ * the recorded SHA is stale for this child and would cause `rebase --onto`
+ * to replay a wildly wrong range. We skip those candidates and keep walking.
+ *
+ * Returns null if no snapshots exist, no recorded tip qualifies, or every
+ * snapshot's recorded tip is still an ancestor of the parent's current tip
+ * (i.e., the parent has only had commits appended, never been rebased —
+ * `merge-base` is still correct).
  */
 export async function findPreRewriteSha(
   meta: StackMetadata,
-  branchName: string,
+  parentBranch: string,
+  childBranch?: string,
 ): Promise<string | null> {
   if (!meta.snapshots || meta.snapshots.length === 0) return null;
 
-  let currentTip: string;
+  let currentParentTip: string;
   try {
-    currentTip = await git.revParse(branchName);
+    currentParentTip = await git.revParse(parentBranch);
   } catch {
     return null;
   }
 
+  let currentChildTip: string | null = null;
+  if (childBranch) {
+    try {
+      currentChildTip = await git.revParse(childBranch);
+    } catch {
+      // Child doesn't exist locally — fall back to parent-only validation
+      currentChildTip = null;
+    }
+  }
+
   // Walk newest → oldest
   for (let i = meta.snapshots.length - 1; i >= 0; i--) {
-    const recorded = meta.snapshots[i]!.branches[branchName];
+    const recorded = meta.snapshots[i]!.branches[parentBranch];
     if (!recorded) continue;
-    if (recorded === currentTip) continue;
-
-    // If the recorded SHA is no longer an ancestor of the current tip,
-    // the branch's history was rewritten between then and now.
-    // That recorded SHA is the orphaned tip we need.
-    const stillAncestor = await git.isAncestor(recorded, currentTip);
-    if (!stillAncestor) {
-      return recorded;
+    if (recorded === currentParentTip) continue;
+
+    // The recorded SHA must no longer be an ancestor of the parent's current
+    // tip — that's how we detect the parent's history was rewritten.
+    const stillAncestorOfParent = await git.isAncestor(recorded, currentParentTip);
+    if (stillAncestorOfParent) continue;
+
+    // Issue #5 guard: if we know the child, the recorded SHA must still be
+    // an ancestor of the child. Otherwise the child has already been rebased
+    // past this point (or never branched off it) and using it as a base
+    // would replay unrelated history.
+    if (currentChildTip) {
+      const stillAncestorOfChild = await git.isAncestor(recorded, currentChildTip);
+      if (!stillAncestorOfChild) continue;
     }
+
+    return recorded;
   }
 
   return null;

package/src/lib/ui.ts

@@ -1,5 +1,5 @@
 // TUI helpers: tree rendering, formatting, prompts
-import * as p from "@clack/prompts";
+import * as p from "./output.ts";
 import pc from "picocolors";
 import type { Stack, StackMetadata } from "../types.ts";
 import { getOrderedBranches } from "./metadata.ts";