gh-stack 0.17.2 → 0.18.0

package/README.md

@@ -83,12 +83,20 @@ create <branch-name> [--description <desc>]
     Create a new git branch off the current branch and add it to
     the stack. The current branch must already be tracked.
 
-add [branch]
+add [branch] [--parent <branch>]
     Track an EXISTING local branch (default: the current branch) in a
     stack — without pushing or opening a PR. Walks local ancestry: if the
     branch sits on top of an existing stack it's adopted into it (parent
     auto-detected); otherwise a new stack is created from the chain.
 
+    --parent <branch>: stack it directly on <branch> (which it must
+    already be based on), tracking <branch> first if needed. Use this
+    for a branch with no commits of its own yet — it sits AT its
+    parent's tip, so ancestry can't tell which is the parent and it
+    would otherwise be rooted at trunk (init/add warn when this
+    happens). It also re-homes an already-tracked branch, but only
+    when it's alone in its stack and has no PR.
+
     Use this for a WIP branch you've created with `git checkout -b` but
     aren't ready to submit. It fills the gap between creating a branch and
     `submit`: until a branch is tracked, `sync`/`restack`/navigation don't
@@ -152,11 +160,16 @@ ls
 ### Stack Management
 
 ```
-restack [--resume] [--dry-run] [--verbose]
+restack [--resume] [--dry-run] [--no-push] [--verbose]
     Rebase the current branch and all descendants onto their parents.
     Uses metadata snapshots to recover the correct rebase base even
     after a parent's history has been rewritten.
 
+    --no-push (or GH_STACK_NO_PUSH=1): rebase locally only, and list
+    the refs left ahead of origin. It overrides --yes for pushes, so
+    an agent can restack unattended without publishing anything. An
+    interrupted --no-push run stays local-only on --resume.
+
     On conflict:
         git rebase --continue
         gh-stack restack --resume
@@ -169,7 +182,7 @@ restack --onto <ref>
     onto main once the parent stack has merged — only the stack's own
     commits replay onto the new base.
 
-sync [--dry-run]
+sync [--dry-run] [--no-push]
     Fetch main, rebase the base branch onto main, then restack all
     children. Snapshots every branch's pre-sync tip so children can be
     correctly rebased even though their parent's history was rewritten.
@@ -179,6 +192,10 @@ sync [--dry-run]
     own commits replay — instead of replaying the now-squashed commits
     and conflicting.
 
+    --no-push (or GH_STACK_NO_PUSH=1): as for restack. Also skips
+    retargeting a PR's base after advancing past a merged bottom;
+    the next `submit` pushes and retargets together.
+
 merge [--dry-run] [-d|--delete-branch] [--collapse]
 merge --approved [--collapse] [--dry-run] [-d|--delete-branch]
 merge --base [--dry-run] [-d|--delete-branch]
@@ -266,9 +283,13 @@ log
 
 update-prs [--force]
     Refresh the "📚 Stacked on" visualization block in every PR
-    description for the current stack. PRs whose rendered block is
-    unchanged are skipped; --force rewrites all of them. (submit does
-    this automatically — use this to refresh without pushing.)
+    description for the current stack. Each PR's live description is
+    checked, so a block removed by an outside edit (`gh pr edit`, the
+    GitHub UI) is restored; PRs already showing the current block are
+    skipped, and --force rewrites all of them. A tracked branch with no
+    recorded PR is looked up on GitHub first, so a PR opened with
+    `gh pr create` is adopted. (submit refreshes the block too, but
+    compares against what it last wrote — use update-prs to repair.)
 
 stacks [--current] [--json]
     List all stacks and their topology. Read-only and network-free —
@@ -322,11 +343,14 @@ learn [--skill] [--harness <name>] [--global] [--force]
 
 `--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.
 
+If a command needs to prompt but stdin isn't a TTY, it exits 1 with the prompt it would have shown, instead of waiting for an answer that can't arrive. Set `GH_STACK_YES=1` (or pass `--yes`) in that context.
+
 ## Environment Variables
 
 ```
 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_PUSH=1     restack/sync never push (same as --no-push; wins over --yes)
 GH_STACK_NO_COLOR=1    Disable colored output
 ```
 
@@ -518,6 +542,9 @@ gh-stack submit -n               # Or auto-generate titles
 gh-stack sync
 gh-stack restack
 
+# Rebase without publishing (e.g. before a human approves the push)
+GH_STACK_NO_PUSH=1 gh-stack restack
+
 # Structured output
 gh-stack status --json
 gh-stack status --current --json

package/package.json

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

package/src/commands/add.ts

@@ -13,7 +13,7 @@ import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { gateLegacyMetadata } from "../lib/safety.ts";
 import { readMetadata, writeMetadata, findStackForBranch, stackBase } from "../lib/metadata.ts";
-import { resolveOrCreateStack } from "../lib/chain.ts";
+import { colocatedBranches, resolveOrCreateStack } from "../lib/chain.ts";
 import type { StackMetadata } from "../types.ts";
 
 export default async function add(args: string[]): Promise<void> {
@@ -22,26 +22,40 @@ export default async function add(args: string[]): Promise<void> {
 gh-stack add — track an existing local branch in a stack (no push, no PR)
 
 USAGE
-  gh-stack add [branch]
+  gh-stack add [branch] [--parent <branch>]
 
 Registers the branch (default: the current branch) into a stack so sync,
 restack, and navigation work before you've submitted it. Walks local ancestry:
 if the branch sits on top of an existing stack it's adopted into that stack;
 otherwise a new stack is created from the chain, rooted at the trunk.
 
+OPTIONS
+  --parent <branch>  Stack the branch directly on <branch> instead of detecting
+                     it (which must already be based on it). Needed when the
+                     branch has no commits of its own yet, since it then sits AT
+                     its parent's tip and ancestry can't tell them apart.
+                     Also re-homes an already-tracked branch, when it's alone in
+                     its stack and has no PR (e.g. a mistaken ${"`"}init${"`"} at trunk).
+
 Network-free — nothing is pushed and no PR is opened. Run ${"`"}gh-stack submit${"`"} when
 you're ready to publish.
 
 EXAMPLES
   gh-stack add                    Track the current branch
   gh-stack add my-wip-branch      Track a specific local branch
+  gh-stack add --parent feat-1    Track the current branch on top of feat-1
 `);
     return;
   }
 
   await gateLegacyMetadata();
 
-  const positional = args.find((a) => !a.startsWith("-"));
+  let parentFlag: string | undefined;
+  let positional: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--parent" && args[i + 1]) parentFlag = args[++i];
+    else if (!args[i]!.startsWith("-")) positional ??= args[i];
+  }
   const branch = positional ?? (await git.currentBranch());
 
   if (!(await git.localBranchExists(branch))) {
@@ -65,9 +79,15 @@ EXAMPLES
     stacks: {},
   };
 
+  if (parentFlag) {
+    await addUnderParent(meta, branch, parentFlag, trunk);
+    return;
+  }
+
   const already = findStackForBranch(meta, branch);
   if (already) {
     p.log.info(`${pc.yellow(branch)} is already tracked in stack ${pc.yellow(already)}.`);
+    await warnIfColocated(branch, trunk);
     return;
   }
 
@@ -100,7 +120,115 @@ EXAMPLES
   for (const b of resolution.addedBranches) {
     console.log(`  ${pc.green("+")} ${b}`);
   }
+  if (resolution.created && resolution.chain.length === 1) await warnIfColocated(branch, trunk);
+
+  p.outro(
+    `Tracked — ${pc.green("gh-stack sync")}/${pc.green("restack")} now work. ${pc.dim("Run")} ${pc.green("gh-stack submit")} ${pc.dim("to open PRs.")}`,
+  );
+}
 
+/**
+ * A branch with no commits of its own sits AT its parent's tip, so ancestry
+ * can't find the parent and it gets rooted at trunk. Say so, and how to fix it,
+ * rather than leaving a stack that `sync` would later rebase onto trunk —
+ * replaying the parent's commits. (#37)
+ */
+export async function warnIfColocated(branch: string, trunk: string): Promise<void> {
+  const same = await colocatedBranches(branch, trunk);
+  if (same.length === 0) return;
+  p.log.warn(
+    `${pc.yellow(branch)} has no commits of its own — it shares its tip with ${same.map((b) => pc.yellow(b)).join(", ")}, so it was rooted at ${trunk}.\n` +
+      `  If it belongs on one of those, re-home it:\n` +
+      same.map((b) => `    ${pc.green(`gh-stack add ${branch} --parent ${b}`)}`).join("\n"),
+  );
+}
+
+/**
+ * `add --parent`: stack `branch` directly on `parent`, tracking `parent` first
+ * (from its own ancestry) if needed. An already-tracked branch is re-homed only
+ * when that can't lose anything: it's alone in its stack and has no PR — the
+ * shape a mistaken `init` at trunk leaves behind. Metadata-only; the branch
+ * must already be based on `parent`. (#37)
+ */
+async function addUnderParent(
+  meta: StackMetadata,
+  branch: string,
+  parent: string,
+  trunk: string,
+): Promise<void> {
+  if (parent === branch) {
+    p.cancel(`A branch can't be its own parent.`);
+    process.exit(1);
+  }
+  if (parent === trunk || parent === "main" || parent === "master") {
+    p.cancel(
+      `--parent is for stacking on a feature branch. To root ${pc.yellow(branch)} at ${trunk}, run ${pc.green("gh-stack add")} without --parent.`,
+    );
+    process.exit(1);
+  }
+  if (!(await git.localBranchExists(parent))) {
+    p.cancel(`Branch ${pc.yellow(parent)} doesn't exist locally.`);
+    process.exit(1);
+  }
+  if (!(await git.isAncestor(parent, branch))) {
+    p.cancel(
+      `${pc.yellow(branch)} isn't based on ${pc.yellow(parent)} — rebase it first:\n\n    ${pc.green(`git rebase ${parent} ${branch}`)}`,
+    );
+    process.exit(1);
+  }
+
+  const oldStackName = findStackForBranch(meta, branch);
+  const oldBranch = oldStackName ? meta.stacks[oldStackName]!.branches[branch]! : null;
+
+  if (oldStackName && oldBranch) {
+    if (oldBranch.parent === parent) {
+      p.log.info(`${pc.yellow(branch)} is already stacked on ${pc.yellow(parent)}.`);
+      return;
+    }
+    const oldStack = meta.stacks[oldStackName]!;
+    const alone = Object.keys(oldStack.branches).length === 1;
+    if (!alone || oldBranch.pr != null) {
+      p.cancel(
+        `${pc.yellow(branch)} is already tracked in stack ${pc.yellow(oldStackName)}` +
+          (oldBranch.pr != null ? ` with PR #${oldBranch.pr}` : " alongside other branches") +
+          ` — re-homing it could strand them, so add --parent won't move it.`,
+      );
+      process.exit(1);
+    }
+  }
+
+  // Track the parent first, from its own ancestry, if it isn't yet. Resolved
+  // before dropping the branch's old stack so a failure leaves nothing changed.
+  let targetStackName = findStackForBranch(meta, parent);
+  const adoptedParents: string[] = [];
+  if (!targetStackName) {
+    try {
+      const res = await resolveOrCreateStack(meta, parent, trunk);
+      targetStackName = res.stackName;
+      adoptedParents.push(...res.addedBranches);
+    } catch (err) {
+      p.cancel((err as Error).message);
+      process.exit(1);
+    }
+  }
+
+  // Drop the throwaway one-branch stack. Deleted, not archived: restoring it
+  // would track the branch in two stacks at once.
+  if (oldStackName && oldStackName !== targetStackName) delete meta.stacks[oldStackName];
+
+  const target = meta.stacks[targetStackName]!;
+  target.branches[branch] = { ...oldBranch, parent };
+  target.last_branch = branch;
+  meta.current_stack = targetStackName;
+  await writeMetadata(meta);
+
+  p.intro(pc.cyan("Add to Stack"));
+  for (const b of adoptedParents) console.log(`  ${pc.green("+")} ${b}`);
+  p.log.success(
+    oldStackName
+      ? `Re-homed ${pc.yellow(branch)} onto ${pc.yellow(parent)} in stack ${pc.yellow(targetStackName)} ${pc.dim(`(removed one-branch stack ${oldStackName})`)}`
+      : `Added ${pc.yellow(branch)} onto ${pc.yellow(parent)} in stack ${pc.yellow(targetStackName)}`,
+  );
   p.outro(
     `Tracked — ${pc.green("gh-stack sync")}/${pc.green("restack")} now work. ${pc.dim("Run")} ${pc.green("gh-stack submit")} ${pc.dim("to open PRs.")}`,
   );

package/src/commands/init.ts

@@ -13,6 +13,7 @@ import {
 import { getPrNumber } from "../lib/github.ts";
 import { isAutoYes } from "../lib/ui.ts";
 import { detectBranchChain } from "../lib/chain.ts";
+import { warnIfColocated } from "./add.ts";
 import { gateLegacyMetadata } from "../lib/safety.ts";
 import type { StackMetadata, Branch } from "../types.ts";
 
@@ -151,6 +152,9 @@ export default async function init(args: string[]): Promise<void> {
 
   p.outro(pc.green(`Stack ${pc.yellow(stackName)} created with ${chain.length} branch(es)!`));
 
+  // A zero-commit branch can't see its parent through ancestry (#37).
+  if (chain.length === 1) await warnIfColocated(branch, trunk);
+
   // Next steps
   console.log();
   if (chain.length === 1) {

package/src/commands/restack.ts

@@ -19,8 +19,21 @@ import { takeSnapshot, resolveRestackBoundary, findRecordedBaseTip } from "../li
 import { confirmAction } from "../lib/ui.ts";
 import type { StackMetadata } from "../types.ts";
 
+/**
+ * `--no-push` / `GH_STACK_NO_PUSH=1`: rebase locally, never publish (#36).
+ * Module-level because every rebase path funnels through `pushBranchRef`.
+ * Wins over `--yes`, which still auto-accepts the rebases themselves.
+ */
+let noPush = false;
+
+/** Whether `--no-push` (or `GH_STACK_NO_PUSH=1`) is in effect for these args. */
+export function wantsNoPush(args: string[]): boolean {
+  return args.includes("--no-push") || process.env.GH_STACK_NO_PUSH === "1";
+}
+
 export default async function restack(args: string[]): Promise<void> {
   const dryRun = args.includes("--dry-run");
+  noPush = wantsNoPush(args);
   const resume = args.includes("--resume");
   const verbose = args.includes("--verbose") || args.includes("-v");
 
@@ -42,6 +55,8 @@ USAGE
 OPTIONS
   --onto <ref> Re-root the stack onto a new base ref (changes stack base)
   --yes, -y   Skip confirmations (auto-accept all rebases and pushes)
+  --no-push   Rebase locally only — never push (also GH_STACK_NO_PUSH=1).
+              Wins over --yes for pushes; rebases are still auto-accepted
   --resume    Resume after resolving rebase conflicts
   --dry-run   Show what would happen without executing
   --verbose   Show diagnostic info (snapshot vs merge-base)
@@ -49,6 +64,8 @@ OPTIONS
 EXAMPLES
   gh-stack restack              Interactive (prompts before each rebase)
   gh-stack restack --yes        Non-interactive (for agents/CI)
+  gh-stack restack --yes --no-push
+                                Non-interactive, local-only (review first)
   gh-stack restack --resume     Continue after resolving conflicts
   gh-stack restack --onto main  Re-root a split stack onto main after its
                                 parent stack has merged
@@ -110,6 +127,21 @@ ALIASES
   // when a push didn't take. (#12)
   if (!dryRun) {
     const stale = await findStaleRefs(touched, meta);
+    if (stale.length > 0 && noPush) {
+      // Expected under --no-push: report what's ahead of origin so a later
+      // submit/restack knows what to publish, but don't fail the run.
+      console.log();
+      p.log.info("Not pushed (--no-push) — these refs are ahead of origin:");
+      for (const { branch, local, remote } of stale) {
+        console.log(`  ${pc.yellow("↑")} ${branch}  local ${local.slice(0, 8)}  origin ${remote}`);
+      }
+      console.log();
+      console.log(
+        `  Publish when ready: ${pc.green("gh-stack restack")} or ${pc.green("gh-stack submit")}`,
+      );
+      p.outro(pc.green("Stack Restack Complete (local only)"));
+      return;
+    }
     if (stale.length > 0) {
       console.log();
       p.log.error("Some branch refs are NOT in sync with origin:");
@@ -185,6 +217,8 @@ async function handleResume(
     p.cancel("No saved state found. Nothing to resume.");
     process.exit(1);
   }
+  // An interrupted --no-push run stays local-only when resumed.
+  if (state.no_push) noPush = true;
 
   // Check if rebase is still in progress
   if (await git.isRebaseInProgress()) {
@@ -597,6 +631,7 @@ async function processChain(
       current_index: i,
       stack_name: stackName,
       chain,
+      ...(noPush && { no_push: true }),
     });
 
     let success: boolean;
@@ -672,6 +707,8 @@ function branchHasPr(meta: StackMetadata, branch: string): boolean {
 
 async function pushBranchRef(meta: StackMetadata, branch: string): Promise<void> {
   if (branch === "main" || branch === "master") return;
+  // --no-push: leave origin alone; the end-of-run summary lists what's ahead.
+  if (noPush) return;
 
   const localSha = await git.revParse(branch);
   const hasRemote = await git.remoteBranchExists(branch);

package/src/commands/sync.ts

@@ -17,20 +17,27 @@ import { confirmAction } from "../lib/ui.ts";
 import { getPrInfo } from "../lib/github.ts";
 import { planMerges, advanceNewBottom, type BranchReview } from "../lib/advance.ts";
 import type { StackMetadata } from "../types.ts";
+import { wantsNoPush } from "./restack.ts";
 
 export default async function sync(args: string[]): Promise<void> {
   const dryRun = args.includes("--dry-run");
+  const noPush = wantsNoPush(args);
 
   if (args.includes("--help")) {
     console.log(`
 gh-stack sync — Sync base with main + restack all
 
 USAGE
-  gh-stack sync [--dry-run]
+  gh-stack sync [--dry-run] [--no-push]
 
 Fetches latest main, rebases the base branch onto main,
 then restacks all children. Equivalent to running restack
 with the base branch included.
+
+OPTIONS
+  --dry-run   Show what would happen without executing
+  --no-push   Rebase locally only — never push or retarget PRs
+              (also GH_STACK_NO_PUSH=1). Wins over --yes for pushes
 `);
     return;
   }
@@ -91,7 +98,7 @@ with the base branch included.
   // them. A plain rebase onto main would then replay their now-squashed commits
   // and conflict — so advance past them (re-rooting the survivor onto main with
   // `--onto`) before the normal sync runs. (#20)
-  const advance = await advanceMergedBottoms(meta, stackName, base, dryRun);
+  const advance = await advanceMergedBottoms(meta, stackName, base, dryRun, noPush);
   if (advance.drained) {
     p.outro(pc.green("Bottom PR(s) already merged — stack fully drained & archived."));
     return;
@@ -178,6 +185,7 @@ with the base branch included.
       current_index: 0,
       stack_name: stackName,
       chain: ordered,
+      ...(noPush && { no_push: true }),
     });
 
     p.log.info("Rebasing onto origin/main...");
@@ -194,7 +202,11 @@ with the base branch included.
     p.log.success("Base branch rebased onto main");
 
     // Prompt to push base
-    await promptForcePush(baseBranch);
+    if (noPush) {
+      p.log.info(`Not pushing ${pc.yellow(baseBranch)} (--no-push) — it's now ahead of origin`);
+    } else {
+      await promptForcePush(baseBranch);
+    }
   }
 
   // Step 2: Restack children
@@ -218,7 +230,7 @@ with the base branch included.
   // Switch to first child and run restack
   if (children.length > 0) {
     await git.checkout(children[0]!);
-    await restack(dryRun ? ["--dry-run"] : []);
+    await restack([...(dryRun ? ["--dry-run"] : []), ...(noPush ? ["--no-push"] : [])]);
   }
 }
 
@@ -246,6 +258,7 @@ async function advanceMergedBottoms(
   stackName: string,
   trunk: string,
   dryRun: boolean,
+  noPush: boolean,
 ): Promise<AdvanceOutcome> {
   const stack = meta.stacks[stackName]!;
   const ordered = getOrderedBranches(stack);
@@ -302,6 +315,7 @@ async function advanceMergedBottoms(
         childPr,
         targetRef,
         recordedBase: trunk,
+        push: !noPush,
       });
       if (!res.ok) {
         console.log();

package/src/commands/update-prs.ts

@@ -17,6 +17,7 @@ import {
 } from "../lib/metadata.ts";
 import { ensureMetadata } from "../lib/safety.ts";
 import {
+  findOpenPrForBranch,
   getPrInfo,
   getPrBody,
   updatePrBody,
@@ -102,6 +103,32 @@ function vizHash(viz: string): string {
   return createHash("sha1").update(viz).digest("hex");
 }
 
+/**
+ * Whether a live PR body already carries exactly this viz block. GitHub
+ * stores bodies edited in its web UI with CRLF line endings, so normalize
+ * before comparing — otherwise every such PR would look perpetually stale.
+ */
+export function bodyHasViz(body: string, viz: string): boolean {
+  return body.replace(/\r\n/g, "\n").includes(viz);
+}
+
+/**
+ * Record PR numbers for tracked branches whose PR was opened outside gh-stack
+ * (e.g. `gh pr create`), by looking up the open PR for each PR-less branch.
+ * Only an unambiguous single match is adopted. Returns the branches adopted —
+ * the caller persists metadata when non-empty. (#35)
+ */
+export async function discoverMissingPrs(stack: Stack, ordered: string[]): Promise<string[]> {
+  const missing = ordered.filter((b) => stack.branches[b]!.pr == null);
+  const found = await mapLimit(missing, 8, async (branch) => {
+    const pr = await findOpenPrForBranch(branch);
+    if (pr == null) return null;
+    stack.branches[branch]!.pr = pr;
+    return branch;
+  });
+  return found.filter((b): b is string => b != null);
+}
+
 /** Splice the rendered viz block into a PR body, replacing any existing one. */
 function mergeViz(body: string, viz: string): string {
   let base = body;
@@ -201,6 +228,7 @@ export interface VizResult {
   updated: number; // PRs whose description we PATCHed
   unchanged: number; // PRs skipped because their rendered block was identical
   skipped: number; // branches with no PR
+  skippedBranches: string[]; // …and their names, so callers can say which
   dirty: boolean; // metadata mutated (caller should persist)
 }
 
@@ -213,12 +241,17 @@ export interface VizResult {
  * body: the override is used as the base instead of the current GitHub body,
  * the managed `📚 Stacked on` block is re-merged into it, and the PR is updated
  * even if the viz block itself didn't change.
+ *
+ * `verifyLive` checks each PR whose cached hash matches against its actual
+ * body, so a viz block removed by an external edit (`gh pr edit`, the web UI)
+ * is restored rather than reported "unchanged". It costs one read per PR, so
+ * `update-prs` opts in while `submit` stays on the cheap hash check. (#34)
  */
 export async function refreshStackViz(
   meta: StackMetadata,
   stack: Stack,
   ordered: string[],
-  opts: { force?: boolean; bodyOverrides?: Record<string, string> } = {},
+  opts: { force?: boolean; verifyLive?: boolean; bodyOverrides?: Record<string, string> } = {},
 ): Promise<VizResult> {
   const force = opts.force ?? false;
   const bodyOverrides = opts.bodyOverrides ?? {};
@@ -239,18 +272,34 @@ export async function refreshStackViz(
       const bm = stack.branches[info.branch]!;
       // A body override forces the PATCH even when the viz block is unchanged.
       const overridden = bodyOverrides[info.branch] != null;
-      return { info, viz, hash, bm, needsUpdate: force || overridden || bm.vizHash !== hash };
+      const needsUpdate = force || overridden || bm.vizHash !== hash;
+      return { info, viz, hash, bm, needsUpdate, liveBody: null as string | null };
     });
 
+  if (opts.verifyLive) {
+    await mapLimit(
+      plans.filter((plan) => !plan.needsUpdate),
+      8,
+      async (plan) => {
+        const body = await getPrBody(plan.info.prNumber!);
+        if (body !== null && !bodyHasViz(body, plan.viz)) {
+          plan.needsUpdate = true;
+          plan.liveBody = body;
+        }
+      },
+    );
+  }
+
   const toUpdate = plans.filter((plan) => plan.needsUpdate);
   const unchanged = plans.length - toUpdate.length;
-  const skipped = branchInfos.length - plans.length;
+  const skippedBranches = branchInfos.filter((b) => b.prNumber == null).map((b) => b.branch);
+  const skipped = skippedBranches.length;
 
   const oks = await mapLimit(toUpdate, 8, async (plan) => {
     // `submit -b` replaces the body; otherwise keep the PR's current body and
     // just re-merge the viz block into it.
     const override = bodyOverrides[plan.info.branch];
-    const body = override ?? (await getPrBody(plan.info.prNumber!));
+    const body = override ?? plan.liveBody ?? (await getPrBody(plan.info.prNumber!));
     if (body === null) return false;
     const ok = await updatePrBody(plan.info.prNumber!, mergeViz(body, plan.viz));
     if (ok) plan.bm.vizHash = plan.hash;
@@ -260,7 +309,7 @@ export async function refreshStackViz(
   const updated = oks.filter(Boolean).length;
   if (updated > 0) dirty = true;
 
-  return { updated, unchanged, skipped, dirty };
+  return { updated, unchanged, skipped, skippedBranches, dirty };
 }
 
 export default async function updatePrs(args: string[]): Promise<void> {
@@ -272,8 +321,13 @@ USAGE
   gh-stack update-prs [--force]
 
 Updates all PRs in the current stack with a standardized stack section
-showing the tree structure, PR links, and per-PR stack index. By default
-PRs whose rendered block is unchanged are skipped; --force rewrites all.
+showing the tree structure, PR links, and per-PR stack index. Each PR's
+live description is checked, so a stack section removed by an outside
+edit (gh pr edit, the GitHub UI) is restored. PRs that already show the
+current section are left alone; --force rewrites all.
+
+Tracked branches with no recorded PR are looked up on GitHub first, so a
+PR opened outside gh-stack (e.g. gh pr create) is adopted automatically.
 `);
     return;
   }
@@ -298,17 +352,30 @@ PRs whose rendered block is unchanged are skipped; --force rewrites all.
 
   const s = p.spinner();
   s.start("Updating PR titles & descriptions...");
+  const adopted = await discoverMissingPrs(stack, ordered);
   const titles = await reconcilePrTitles(stack, ordered);
-  const result = await refreshStackViz(meta, stack, ordered, { force });
+  const result = await refreshStackViz(meta, stack, ordered, { force, verifyLive: true });
   s.stop("Done");
 
-  if (titles.dirty || result.dirty) await writeMetadata(meta);
+  if (adopted.length > 0 || titles.dirty || result.dirty) await writeMetadata(meta);
+
+  for (const b of adopted) {
+    p.log.success(
+      `Adopted PR #${stack.branches[b]!.pr} for ${pc.blue(b)} (opened outside gh-stack)`,
+    );
+  }
+  if (result.skippedBranches.length > 0) {
+    p.log.warn(
+      `Skipped ${result.skippedBranches.length} branch(es) with no open PR: ${result.skippedBranches.map((b) => pc.blue(b)).join(", ")}\n` +
+        `  Open them with ${pc.green("gh-stack submit")}`,
+    );
+  }
 
   console.log();
   p.outro(
     pc.green(
       `Updated ${result.updated} description(s), ${titles.updated} title(s)` +
-        (result.unchanged > 0 ? `, ${result.unchanged} unchanged` : "") +
+        (result.unchanged > 0 ? `, ${result.unchanged} already up to date` : "") +
         (result.skipped > 0 ? `, ${result.skipped} without PRs` : ""),
     ),
   );

package/src/lib/advance.ts

@@ -146,8 +146,11 @@ export async function advanceNewBottom(opts: {
   childPr: number | null;
   targetRef: string;
   recordedBase: string;
+  /** false = `--no-push`: rebase + metadata only, leave origin and the PR alone (#36). */
+  push?: boolean;
 }): Promise<AdvanceResult> {
   const { meta, stackName, mergedBranch, child, childPr, targetRef, recordedBase } = opts;
+  const push = opts.push ?? true;
 
   const forkPoint = await resolveForkPoint(meta, mergedBranch, child);
   if (!forkPoint) return { ok: false, reason: "no-fork-point" };
@@ -164,15 +167,23 @@ export async function advanceNewBottom(opts: {
   const ok = await git.rebaseOnto(targetRef, forkPoint, child);
   if (!ok) return { ok: false, reason: "conflict", forkPoint };
 
-  // Push the rebased head first so the PR diff is clean before its base flips.
-  await git.pushStackedBranch(child);
-  if (childPr != null) {
-    const moved = await setPrBase(childPr, recordedBase);
-    if (moved) {
-      p.log.success(`PR #${childPr} base → ${pc.green(recordedBase)}`);
-    } else {
-      p.log.warn(`Could not retarget PR #${childPr} — set its base to ${recordedBase} manually`);
+  if (push) {
+    // Push the rebased head first so the PR diff is clean before its base flips.
+    await git.pushStackedBranch(child);
+    if (childPr != null) {
+      const moved = await setPrBase(childPr, recordedBase);
+      if (moved) {
+        p.log.success(`PR #${childPr} base → ${pc.green(recordedBase)}`);
+      } else {
+        p.log.warn(`Could not retarget PR #${childPr} — set its base to ${recordedBase} manually`);
+      }
     }
+  } else if (childPr != null) {
+    // Retargeting the base without pushing the rebased head would show the
+    // merged commits in the PR diff, so leave both for `submit` to reconcile.
+    p.log.info(
+      `Not pushing ${pc.yellow(child)} or retargeting PR #${childPr} (--no-push) — ${pc.green("gh-stack submit")} publishes both`,
+    );
   }
 
   // Metadata last: re-parents child (and siblings) onto the merged branch's

package/src/lib/chain.ts

@@ -53,6 +53,26 @@ export async function detectBranchChain(currentBranch: string, trunk: string): P
   return chain;
 }
 
+/**
+ * Local branches (other than trunk) whose tip is the SAME commit as `branch`.
+ * A branch with no commits of its own sits at its parent's tip rather than
+ * above it, so `detectBranchChain` can't see the parent — and from ancestry
+ * alone the two are indistinguishable. Callers use this to warn instead of
+ * silently rooting the branch at trunk. (#37)
+ */
+export async function colocatedBranches(branch: string, trunk: string): Promise<string[]> {
+  const tip = await git.revParse(branch);
+  const excluded = new Set([branch, trunk, "main", "master"]);
+  const out: string[] = [];
+  for (const [other, sha] of await git.localBranchTips()) {
+    if (excluded.has(other) || sha !== tip) continue;
+    // A branch sitting on trunk's tip isn't a stack parent, just trunk.
+    if (await git.isAncestor(other, trunk)) continue;
+    out.push(other);
+  }
+  return out;
+}
+
 export interface StackResolution {
   stackName: string;
   base: string; // effective base of the resulting stack (for display)

package/src/lib/git.ts

@@ -346,6 +346,20 @@ export async function allLocalBranches(): Promise<string[]> {
   return result.trim().split("\n").filter(Boolean);
 }
 
+/**
+ * Map every local branch to its tip SHA, in one call.
+ */
+export async function localBranchTips(): Promise<Map<string, string>> {
+  const result =
+    await $`git for-each-ref --format=${"%(refname:short) %(objectname)"} refs/heads`.text();
+  const tips = new Map<string, string>();
+  for (const line of result.trim().split("\n").filter(Boolean)) {
+    const [name, sha] = line.split(" ");
+    if (name && sha) tips.set(name, sha);
+  }
+  return tips;
+}
+
 /**
  * Determine the trunk branch name. Prefers "main", falls back to "master"
  * if only that exists locally. Defaults to "main" when neither is present.

package/src/lib/github.ts

@@ -40,6 +40,26 @@ export async function getPrNumber(branch: string): Promise<number | null> {
   }
 }
 
+/**
+ * Find the open PR whose head is `branch`, for adopting a PR opened outside
+ * gh-stack. Unlike getPrNumber, returns null unless there is exactly one match
+ * — a fork with the same branch name must never be adopted by accident.
+ */
+export async function findOpenPrForBranch(branch: string): Promise<number | null> {
+  try {
+    const out =
+      await $`gh pr list --head ${branch} --state open --json number --jq '.[].number'`.text();
+    const nums = out
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean)
+      .map((n) => parseInt(n, 10));
+    return nums.length === 1 && !isNaN(nums[0]!) ? nums[0]! : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Get PR info for a specific PR number.
  */

package/src/lib/output.ts

@@ -7,9 +7,11 @@
 //   - 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 —
+// Interactive prompts (text, confirm, select) are unchanged by plain mode —
 // plain mode is about output, not interactivity. Agents already pair --plain
-// with --yes/GH_STACK_YES so the interactive paths aren't reached.
+// with --yes/GH_STACK_YES so the interactive paths aren't reached. If one IS
+// reached with no TTY on stdin, nothing can ever answer it, so we fail fast
+// instead of blocking forever (#33).
 import * as clack from "@clack/prompts";
 
 let _plain = false;
@@ -27,11 +29,38 @@ function strip(s: string | undefined): string {
   return (s ?? "").replace(ANSI_RE, "");
 }
 
-// ── Interactive prompts (unchanged) ──
+// ── Interactive prompts ──
 export const isCancel = clack.isCancel;
-export const text = clack.text;
-export const confirm = clack.confirm;
-export const select = clack.select;
+
+/**
+ * Exit non-zero instead of prompting when stdin isn't a TTY. A prompt there
+ * can never be answered, and it would otherwise hang (holding the repo) past
+ * the caller's timeout. (#33)
+ */
+function ensureInteractive(message: string): void {
+  if (process.stdin.isTTY) return;
+  console.error(
+    `gh-stack: refusing to prompt — stdin is not a TTY.\n` +
+      `  Prompt: ${strip(message)}\n` +
+      `  Pass --yes (or set GH_STACK_YES=1) to confirm automatically.`,
+  );
+  process.exit(1);
+}
+
+export const text: typeof clack.text = (opts) => {
+  ensureInteractive(opts.message);
+  return clack.text(opts);
+};
+
+export const confirm: typeof clack.confirm = (opts) => {
+  ensureInteractive(opts.message);
+  return clack.confirm(opts);
+};
+
+export const select: typeof clack.select = (opts) => {
+  ensureInteractive(opts.message);
+  return clack.select(opts);
+};
 
 // ── Banner / error ──
 export function intro(message?: string): void {

package/src/lib/using-gh-stack.md

@@ -64,6 +64,13 @@ export GH_STACK_YES=1     # skip every confirmation, plain output
   of generic auto-generated ones (see below).
 - Commands that rebase (`restack`, `sync`, `merge`) **refuse to run on a dirty
   tree** — commit or stash first.
+- **`--yes` also accepts pushes.** To rebase without publishing (e.g. until a
+  human approves), add `--no-push` to `restack`/`sync`, or export
+  `GH_STACK_NO_PUSH=1`. It wins over `--yes` for pushes and lists what's ahead
+  of origin at the end.
+- A prompt reached without a TTY on stdin **exits 1** (naming the prompt)
+  instead of hanging. If you see `refusing to prompt`, re-run with
+  `GH_STACK_YES=1`.
 
 ## Core workflow
 
@@ -94,10 +101,17 @@ created a branch with `git checkout -b` and want to `sync`/`restack` it _before_
 opening a PR, `add` registers it in a stack (network-free — no push, no PR):
 
 ```bash
-gh-stack add           # track the current branch
-gh-stack add <branch>  # track a named branch
+gh-stack add                     # track the current branch
+gh-stack add <branch>            # track a named branch
+gh-stack add --parent <branch>   # stack the current branch directly on <branch>
 ```
 
+**A branch with no commits yet can't be placed by ancestry.** It sits _at_ its
+parent's tip, so `init`/`add` root it at trunk and warn that it "has no commits
+of its own". Fix it with `gh-stack add --parent <parent>`, which tracks the
+parent too if needed. `--parent` also re-homes a branch that's already tracked,
+but only when it's alone in its stack with no PR.
+
 It walks local ancestry: a branch sitting on top of an existing stack is adopted
 into it (parent auto-detected); otherwise a new stack is created from the chain.
 This resolves the catch-22 where `sync`/`restack` said "not in any stack" for a
@@ -163,6 +177,7 @@ gh-stack checkout      # interactive picker (alias: co)
 gh-stack sync          # fetch trunk, rebase base onto it, restack ALL children
 gh-stack restack       # rebase current branch + descendants onto their parents
 gh-stack restack --dry-run
+gh-stack restack --no-push   # rebase locally only (also: GH_STACK_NO_PUSH=1)
 ```
 
 **⚠️ Restack propagates UPWARD from the current branch.** Run it from the
@@ -229,7 +244,7 @@ gh-stack rename        # rename a tracked branch (keeps metadata in sync)
 gh-stack undo          # restore from the last snapshot
 gh-stack archive       # manage archived stacks
 gh-stack doctor        # migrate & repair stack metadata
-gh-stack update-prs    # refresh stack visualization in PR descriptions
+gh-stack update-prs    # repair stack viz in PR descriptions + adopt PRs opened with gh pr create
 ```
 
 ## Stack visualization

package/src/types.ts

@@ -64,6 +64,8 @@ export interface RestackState {
   current_index: number;
   stack_name: string;
   chain: string[];
+  /** The interrupted run was `--no-push`; `--resume` keeps it local-only (#36). */
+  no_push?: boolean;
 }
 
 // PR info from GitHub API