gh-stack 0.17.2 → 0.19.0

package/src/lib/remote-guard.ts

@@ -0,0 +1,281 @@
+// Before a run rewrites branches, make sure origin doesn't hold content the
+// local branches lack (#28).
+//
+// The incident: `merge --collapse` squash-merged PR2 into PR1's branch on
+// GitHub. The local PR1 never pulled that squash commit, a `sync` rebased the
+// local PR1 and force-pushed it, and the base PR silently lost every child's
+// content. `--force-with-lease` doesn't protect against this once the
+// remote-tracking ref has been fetched.
+//
+// The hard part is not crying wolf. After a `--no-push` restack, or a run
+// interrupted before its pushes, origin legitimately holds the *pre-rewrite*
+// versions of local commits. Those aren't new: local had them and rewrote them
+// on purpose. So a commit on origin counts as new content only if
+//   1. it was never in the local branch's history (its reflog, or a tip a
+//      snapshot recorded), and
+//   2. it isn't patch-equivalent to a local commit.
+import { $ } from "bun";
+import pc from "picocolors";
+import * as p from "./output.ts";
+import * as git from "./git.ts";
+import { isAutoYes } from "./ui.ts";
+import type { StackMetadata } from "../types.ts";
+
+/** A branch whose origin copy differs but couldn't be checked. */
+export interface Unverified {
+  branch: string;
+  remoteSha: string;
+  reason: string;
+}
+
+export interface RemoteOnlyContent {
+  branch: string;
+  localSha: string;
+  remoteSha: string;
+  /** "sha subject", oldest first. */
+  commits: string[];
+  /** Local is simply behind origin (a fast-forward brings the commits in). */
+  behind: boolean;
+}
+
+/** How many reflog entries count as "versions local already had". */
+const REFLOG_DEPTH = 300;
+
+/**
+ * For each branch with a copy on origin that differs from local, the commits
+ * origin has that are new content (see the module comment). `cleared` maps the
+ * branches whose origin copy differs but holds nothing new to the origin tip
+ * that was checked. `unverified` lists branches whose origin copy couldn't be
+ * checked (not fetched, or git failed): never cleared, the caller fails closed.
+ */
+export async function findRemoteOnlyContent(
+  meta: StackMetadata,
+  branches: string[],
+): Promise<{
+  found: RemoteOnlyContent[];
+  cleared: Map<string, string>;
+  unverified: Unverified[];
+}> {
+  const found: RemoteOnlyContent[] = [];
+  const cleared = new Map<string, string>();
+  const unverified: Unverified[] = [];
+  const heads = await git.remoteHeads();
+  const trunk = await git.trunkBranch();
+
+  const targets: { branch: string; local: string; remote: string }[] = [];
+  for (const branch of new Set(branches)) {
+    if (branch === trunk || branch === "main" || branch === "master") continue;
+    const remote = heads.get(branch);
+    if (!remote || !(await git.localBranchExists(branch))) continue;
+    const local = await git.revParse(branch);
+    if (remote !== local) targets.push({ branch, local, remote });
+  }
+  if (targets.length === 0) return { found, cleared, unverified };
+
+  // Origin's trunk too: commits that came from it (GitHub's "Update branch"
+  // merges main into a PR branch) aren't the user's to lose.
+  const trunkTip = heads.get(trunk);
+  await git.fetchObjectsOnly([
+    ...targets.map((t) => `refs/heads/${t.branch}`),
+    ...(trunkTip ? [`refs/heads/${trunk}`] : []),
+  ]);
+
+  for (const { branch, local, remote } of targets) {
+    if (!(await git.refExists(`${remote}^{commit}`))) {
+      unverified.push({
+        branch,
+        remoteSha: remote,
+        reason: `origin/${branch} couldn't be fetched`,
+      });
+      continue;
+    }
+    if (await git.isAncestor(remote, local)) {
+      cleared.set(branch, remote); // local already has all of it
+      continue;
+    }
+
+    const known = [
+      local,
+      ...(await reflogTips(branch)),
+      ...snapshotTips(meta, branch),
+      ...(trunkTip ? [trunkTip] : []),
+    ];
+    const candidates = await revListLines([
+      "--ignore-missing",
+      "--reverse",
+      "--no-merges",
+      remote,
+      "--not",
+      ...new Set(known),
+    ]);
+    const unmatched = await revListLines([
+      "--cherry-pick",
+      "--right-only",
+      "--no-merges",
+      `${local}...${remote}`,
+    ]);
+    if (candidates === null || unmatched === null) {
+      // No verdict is not a clean verdict: this branch stays unchecked.
+      unverified.push({ branch, remoteSha: remote, reason: "git rev-list failed comparing it" });
+      continue;
+    }
+    const fresh = candidates.filter((sha) => unmatched.includes(sha));
+    if (fresh.length === 0) {
+      cleared.set(branch, remote);
+      continue;
+    }
+    found.push({
+      branch,
+      localSha: local,
+      remoteSha: remote,
+      commits: await oneLines(fresh),
+      behind: await git.isAncestor(local, remote),
+    });
+  }
+  return { found, cleared, unverified };
+}
+
+/** Earlier tips of `refs/heads/<branch>`, newest first. */
+async function reflogTips(branch: string): Promise<string[]> {
+  const { stdout } = await $`git reflog show --format=%H refs/heads/${branch}`.nothrow().quiet();
+  return stdout.toString().split("\n").filter(Boolean).slice(0, REFLOG_DEPTH);
+}
+
+/** Tips of `branch` that snapshots recorded (the pre-rewrite versions). */
+function snapshotTips(meta: StackMetadata, branch: string): string[] {
+  const tips = new Set<string>();
+  for (const snap of meta.snapshots ?? []) {
+    const sha = snap.branches[branch];
+    if (sha) tips.add(sha);
+  }
+  return [...tips];
+}
+
+/** `git rev-list` output, or null if it failed (never an empty "nothing found"). */
+async function revListLines(args: string[]): Promise<string[] | null> {
+  const { stdout, exitCode } = await $`git rev-list ${args}`.nothrow().quiet();
+  if (exitCode !== 0) return null;
+  return stdout.toString().split("\n").filter(Boolean);
+}
+
+/** "abbrev subject" for each sha, in the given order, from one `git log`. */
+async function oneLines(shas: string[]): Promise<string[]> {
+  const { stdout } = await $`git log --no-walk=unsorted --format=${"%h %s"} ${shas}`
+    .nothrow()
+    .quiet();
+  return stdout.toString().split("\n").filter(Boolean);
+}
+
+/**
+ * Stop a run before it rewrites a branch whose origin copy has new content.
+ * Interactive: ask (default no). Under --yes: refuse, since no flag the user
+ * gave said "drop commits from origin". `--overwrite-remote` proceeds. A dry
+ * run only reports.
+ */
+export async function guardRemoteContent(
+  meta: StackMetadata,
+  branches: string[],
+  opts: { command: string; overwrite: boolean; dryRun: boolean },
+): Promise<Map<string, string>> {
+  const { found, cleared, unverified } = await findRemoteOnlyContent(meta, branches);
+  if (found.length === 0 && unverified.length === 0) return cleared;
+
+  if (unverified.length > 0) {
+    console.log();
+    p.log.error(
+      "Couldn't check these branches' copies on origin for commits the local branches lack:",
+    );
+    for (const u of unverified) {
+      console.log(
+        `  ${pc.yellow(u.branch)}  ${pc.dim(`(origin ${u.remoteSha.slice(0, 8)}: ${u.reason})`)}`,
+      );
+    }
+    console.log();
+    console.log(
+      `  ${opts.command} would rebase or force-push them without knowing what's there. Look first:`,
+    );
+    for (const u of unverified) {
+      console.log(
+        `    ${pc.green(`git fetch origin ${u.branch} && git log ${u.branch}..origin/${u.branch}`)}`,
+      );
+    }
+    console.log(`  Then re-run ${pc.green(`gh-stack ${opts.command}`)}.`);
+    console.log(
+      `  Or, to overwrite them regardless: ${pc.green(`gh-stack ${opts.command} --overwrite-remote`)}`,
+    );
+  }
+  if (found.length === 0) return decide(cleared, [], unverified, opts);
+
+  console.log();
+  p.log.error(
+    "Origin has commits that the local branches don't, and they aren't earlier versions of local commits:",
+  );
+  for (const f of found) {
+    console.log(
+      `  ${pc.yellow(f.branch)}  ${pc.dim(`(origin ${f.remoteSha.slice(0, 8)}, local ${f.localSha.slice(0, 8)})`)}`,
+    );
+    for (const c of f.commits) console.log(`    ${pc.red("+")} ${c}`);
+  }
+  console.log();
+  console.log(
+    `  ${opts.command} would rebase or force-push ${found.length === 1 ? "this branch" : "these branches"} without them, and they'd be lost from origin and the PR.`,
+  );
+  console.log(
+    "  This is what happens after `merge --collapse` squashes a child PR into its parent on GitHub.",
+  );
+  console.log();
+  console.log("  Bring them into the local branch first:");
+  for (const f of found) {
+    const shas = f.commits.map((c) => c.split(" ")[0]).join(" ");
+    console.log(
+      `    ${pc.green(f.behind ? `git checkout ${f.branch} && git pull --ff-only origin ${f.branch}` : `git checkout ${f.branch} && git cherry-pick ${shas}`)}`,
+    );
+  }
+  console.log(`  Then re-run ${pc.green(`gh-stack ${opts.command}`)}.`);
+  console.log(
+    `  Or, to drop them on purpose: ${pc.green(`gh-stack ${opts.command} --overwrite-remote`)}`,
+  );
+  return decide(cleared, found, unverified, opts);
+}
+
+/**
+ * What to do about branches with new or unchecked content on origin: report
+ * (dry run), proceed (--overwrite-remote, or an interactive yes), or stop
+ * (--yes, or no). Proceeding clears their checked tips for an explicit lease.
+ */
+async function decide(
+  cleared: Map<string, string>,
+  found: RemoteOnlyContent[],
+  unverified: Unverified[],
+  opts: { overwrite: boolean; dryRun: boolean },
+): Promise<Map<string, string>> {
+  console.log();
+  if (opts.dryRun) {
+    p.log.warn("[DRY RUN] A real run would stop here.");
+    return cleared;
+  }
+  const overwrite = () => {
+    for (const f of found) cleared.set(f.branch, f.remoteSha);
+    for (const u of unverified) cleared.set(u.branch, u.remoteSha);
+    return cleared;
+  };
+  if (opts.overwrite) {
+    p.log.warn(
+      "--overwrite-remote: continuing. Origin's copies of those branches will be overwritten.",
+    );
+    return overwrite();
+  }
+  if (isAutoYes()) {
+    p.cancel("Stopped before rewriting anything (--yes never overwrites what it couldn't check).");
+    process.exit(1);
+  }
+  const ok = await p.confirm({
+    message: "Rewrite anyway, overwriting origin's copies of those branches?",
+    initialValue: false,
+  });
+  if (p.isCancel(ok) || !ok) {
+    p.cancel("Stopped before rewriting anything.");
+    process.exit(1);
+  }
+  return overwrite();
+}

package/src/lib/run-log.ts

@@ -0,0 +1,117 @@
+// The saved state of a restack/sync/join run, read back: is a run still
+// pending, where did it stop, and what did it do (#15, #29).
+//
+// The state itself is written by restack.ts as the run goes (see RestackState).
+// This module only interprets it, so `restack`, `sync`, `merge`, `join` and
+// `undo` agree on what "an interrupted run" means.
+import pc from "picocolors";
+import * as p from "./output.ts";
+import { InvalidRunStateError, clearRestackState, loadRestackState } from "./metadata.ts";
+import type { RestackState, RunLogEntry } from "../types.ts";
+
+/**
+ * The saved run state, or null. A state that can't be used (unreadable, or
+ * from another gh-stack version) is never upgraded: with `discard` (the
+ * `--fresh` path) it's deleted with a note, otherwise this exits 1 saying how
+ * to discard it.
+ */
+export async function loadRunState(opts: { discard?: boolean } = {}): Promise<RestackState | null> {
+  try {
+    return await loadRestackState();
+  } catch (err) {
+    if (!(err instanceof InvalidRunStateError)) throw err;
+    if (opts.discard) {
+      p.log.warn(`Discarding the saved run state at ${err.path}: ${err.reason}.`);
+      await clearRestackState();
+      return null;
+    }
+    p.cancel(
+      `${err.message}\n\n  Discard it and restack from the current branch:\n    ${pc.green("gh-stack restack --fresh")}`,
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * A saved run that hasn't finished: a conflict stop, a kill, failed or held
+ * pushes, or a rebase that was saved as started but never ran (or was
+ * aborted). All of them are resumable; nothing is inferred from the branch
+ * position, since a kill before the rebase started looks just like an abort.
+ */
+export async function findPendingRun(
+  opts: { discard?: boolean } = {},
+): Promise<RestackState | null> {
+  const state = await loadRunState(opts);
+  return state && !state.finished_at ? state : null;
+}
+
+/** Branches whose push failed, was declined or held, and hasn't succeeded since. */
+export function outstandingPushes(state: RestackState): string[] {
+  const out = new Set<string>();
+  for (const e of state.log) {
+    if (e.action === "push-failed" || e.action === "push-declined" || e.action === "push-held") {
+      out.add(e.branch);
+    } else if (e.action === "pushed") {
+      out.delete(e.branch);
+    }
+  }
+  return [...out];
+}
+
+/** Where the run stopped, for "An interrupted sync was detected (stopped at …)". */
+export function stoppedAt(state: RestackState): string {
+  if (state.rebase) return `${state.rebase.branch}: rebasing onto ${state.rebase.onto}`;
+  const next = state.chain[state.current_index];
+  if (next) return next;
+  const unpushed = outstandingPushes(state);
+  if (unpushed.length > 0) return `${unpushed.join(", ")}: not pushed`;
+  return "the end of its chain";
+}
+
+/** What's left for a resume to do, one line per item. */
+export function remainingSteps(state: RestackState): string[] {
+  const steps: string[] = [];
+  for (const b of outstandingPushes(state)) steps.push(`push ${b}`);
+  if (state.rebase) steps.push(`finish rebasing ${state.rebase.branch}, then push it`);
+  const from = state.current_index + (state.rebase ? 1 : 0);
+  const rest = state.chain.slice(from);
+  if (rest.length > 0) steps.push(`restack and push ${rest.join(", ")}`);
+  return steps;
+}
+
+export function formatLogEntry(e: RunLogEntry): string {
+  const b = pc.yellow(e.branch);
+  switch (e.action) {
+    case "rebased":
+      return `${pc.green("✓")} rebased ${b} onto ${e.onto ?? "its parent"}`;
+    case "up-to-date":
+      return `${pc.dim("·")} ${b} already on ${e.onto ?? "its parent"}`;
+    case "rebase-declined":
+      return `${pc.dim("–")} skipped rebasing ${b} (declined)`;
+    case "pushed":
+      return `${pc.green("✓")} pushed ${b}`;
+    case "push-failed":
+      return `${pc.red("✗")} push of ${b} failed`;
+    case "push-declined":
+      return `${pc.yellow("–")} push of ${b} declined`;
+    case "push-held":
+      return `${pc.yellow("⏸")} held ${b} back${e.detail ? ` (${e.detail})` : ""}`;
+    case "local-only":
+      return `${pc.dim("·")} ${b} is local-only (not submitted), not pushed`;
+  }
+}
+
+/** The run's log as indented lines (empty when nothing happened yet). */
+export function formatRunLog(state: RestackState): string[] {
+  return state.log.map((e) => `  ${formatLogEntry(e)}`);
+}
+
+/** "sync, started 2026-10-27 14:03" (local time) */
+const two = (n: number) => String(n).padStart(2, "0");
+
+export function describeRun(state: RestackState): string {
+  const at = state.started_at ? new Date(state.started_at) : null;
+  if (!at || Number.isNaN(at.getTime())) return state.command;
+  const when = `${at.getFullYear()}-${two(at.getMonth() + 1)}-${two(at.getDate())} ${two(at.getHours())}:${two(at.getMinutes())}`;
+  return `${state.command}, started ${when}`;
+}

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

@@ -62,8 +62,25 @@ export GH_STACK_YES=1     # skip every confirmation, plain output
   (network-free) or `gh-stack status --json` (adds PR/CI/review state).
 - **Always pass `-t`/`-b` to `submit`** so PRs get real titles/bodies instead
   of generic auto-generated ones (see below).
+- **Run `gh-stack config` once per repo** to see its defaults. A repo whose
+  `.gh-stack.toml` sets `[submit] draft = true` opens every new PR as a draft
+  without `--draft`; pass `--no-draft` only when you were asked for a
+  ready-for-review PR. `submit --json` reports `draft` for PRs it created.
+- **Need the PR number or URL? Add `--json` to `submit`** instead of running
+  `gh pr view` afterwards. stdout is only the JSON; logs go to stderr.
 - 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` (a repo may also set `[restack] push = false`). It wins
+  over `--yes` for pushes and lists what's ahead of origin at the end; publish
+  later with `gh-stack restack --push`. `merge` and `submit --restack` always
+  push. `restack --resume` keeps the interrupted run's push decision unless you
+  pass `--push`/`--no-push`. `--yes` itself can't come from a config file:
+  always pass it or `GH_STACK_YES=1`.
+- 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,16 +111,47 @@ 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
 tip you hadn't submitted yet. (`submit` still auto-tracks too — `add` is just the
 no-publish path.)
 
+**Splice an existing branch/PR into a stack — `gh-stack join`.** For a branch
+that should have been stacked but was cut from main on its own (often with its
+own PR already open):
+
+```bash
+gh-stack join <branch> --dry-run          # preview: resulting stack + each PR's projected diff
+gh-stack join <branch>                    # insert as the new bottom of the current stack
+gh-stack join <branch> --above <parent>   # insert between <parent> and its children
+```
+
+`join` syncs the incoming branch onto its new parent first, replaying only its
+own commits, then restacks everything above it, pushes, and retargets the PR
+bases on GitHub. **Don't do this by hand with `git rebase`:** rebasing children
+onto a branch that's behind main silently drags merged main commits into their
+diffs. Run `--dry-run` first and check each PR's commit/file count. A conflict
+syncing the incoming branch leaves the stack untouched (resolve,
+`git rebase --continue`, re-run the join); a conflict restacking above it resumes
+with `gh-stack restack --resume`. A branch alone in its own one-branch stack is
+absorbed; one in a larger stack is refused. Unless you pass `--no-push`, the
+incoming branch must already be on origin (`git push -u origin <branch>`). If a
+child was cut from an older, since-rewritten version of the incoming branch,
+join refuses and prints the `git rebase --onto` that drops the stale copies: run
+it, then re-run the join.
+
 ### 2. Push & create PRs — `submit`
 
 `submit` is the workhorse: **idempotent, scope-aware, self-healing**. It pushes
@@ -114,6 +162,7 @@ visualization in every PR body.
 ```bash
 gh-stack submit                       # push downstack + create/update PRs
 gh-stack submit -d                    # create new PRs as drafts
+gh-stack submit --no-draft            # ready for review despite a draft default
 gh-stack submit --dry-run             # preview, no side effects
 gh-stack submit --restack             # then propagate up to children (see below)
 gh-stack submit -t "<title>" -b "<body>"   # explicit title/body for new PRs
@@ -137,6 +186,54 @@ EOF
 )"
 ```
 
+**`submit --json` returns what happened to each branch** (stdout is only the
+JSON document, on every exit; logs go to stderr, so capture stdout alone):
+
+```bash
+gh-stack submit --json -t "<title>" --body-file /tmp/body.md > /tmp/submit.json
+jq -r '.branches[-1].url' /tmp/submit.json     # the current branch's PR
+```
+
+```json
+{
+  "stack": "my-stack",
+  "current_branch": "feat-b",
+  "branches": [
+    {
+      "branch": "feat-a",
+      "parent": "main",
+      "pr": 101,
+      "url": "https://github.com/org/repo/pull/101",
+      "title": "Feat A (1/2)",
+      "action": "unchanged",
+      "pushed": false,
+      "draft": null
+    },
+    {
+      "branch": "feat-b",
+      "parent": "feat-a",
+      "pr": 102,
+      "url": "https://github.com/org/repo/pull/102",
+      "title": "Feat B (2/2)",
+      "action": "created",
+      "pushed": true,
+      "draft": false
+    }
+  ],
+  "error": null
+}
+```
+
+`branches` is the submit scope (trunk → current) in stack order, so on success
+the last entry is the branch you're on. `action` is `created`, `updated`
+(pushed, or base/title/description edited), `unchanged`, or `failed` (with an
+`error`). `draft` is only known for PRs created this run (else `null`). When
+the run stops early (nothing to submit, a bad `--body-file`, a push failure),
+top-level `error` is `{ "message": "..." }` and `branches` lists what happened
+before it. Exit code is 1 whenever `error` is set or any branch `failed`.
+`--json` implies `--no-edit` and can't be combined with `--dry-run` or
+`--restack`; run `gh-stack restack` as a separate step.
+
 **`submit -t`/`-b` also updates an existing PR in place** — pass them while on a
 branch that already has a PR to change just that one (visualization-safe).
 
@@ -163,6 +260,8 @@ 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)
+gh-stack restack --push      # push despite GH_STACK_NO_PUSH / [restack] push = false
 ```
 
 **⚠️ Restack propagates UPWARD from the current branch.** Run it from the
@@ -181,7 +280,27 @@ edit several branches then restack once at the end (only the last branch ends
 up pushed).
 
 **On rebase conflict:** resolve, `git add <files>`, `git rebase --continue`,
-then `gh-stack restack --resume` to finish the remaining branches.
+then `gh-stack restack --resume` to finish the remaining branches. That's the
+command even when the conflict came from `sync`. If you forget `--resume`, a
+bare `restack`/`sync` notices the interrupted run and, under `--yes`, resumes
+it. Don't pass `--fresh` unless you were asked to abandon the run: it discards
+the run's remaining steps. `git rebase --abort` does not end the run; a resume
+runs that rebase again.
+
+**Interrupted or partly pushed run** (killed, timed out, or a push failed):
+run `gh-stack restack --resume`. It continues from the saved state and retries
+the pushes, parents first. If everything already finished it prints the run's
+log and exits 0. A branch whose parent didn't reach origin is never pushed onto
+it (its PR would be diffed against the parent's old history); the run lists it
+as held and exits 1 until `--resume` gets the parent pushed. `merge` and `join`
+refuse to run while a restack/sync is pending.
+
+**"Origin has commits that the local branches don't"** (restack/sync exit 1
+before changing anything): a branch's copy on origin has commits it never had,
+often the squash commit a `merge --collapse` added on GitHub. Run the
+`git pull --ff-only` / `git cherry-pick` lines it prints, then re-run. Don't
+pass `--overwrite-remote` unless you were asked to drop those commits: it
+deletes them from the PR.
 
 **`sync` is self-correcting:** if you merged the bottom PR in the GitHub UI,
 `sync` detects it and advances the stack past the merged branch (re-rooting onto
@@ -220,16 +339,32 @@ Merge is **top-down everywhere** (collapse PRn → PRn-1 → … → base PR, th
 - **`--collapse`** (with `merge` or `merge --approved`): stop after collapsing
   into the base PR — review on GitHub, then re-run `merge` to finish.
 
+After a collapse, the base branch on origin holds the children's squash
+commits. Pull it before touching it locally (`git pull --ff-only origin <base>`).
+Before the base PR goes to main, `merge` checks those commits are still in it.
+If it exits 2 with "PR #N's changes are missing from PR #base", the base was
+rewritten without them: follow the printed steps (`gh api … | git am`) and
+re-run `merge`. If it exits 2 saying PR #N's changes are UNVERIFIED, nothing
+is known to be lost, but it couldn't be checked (often a GitHub or network
+hiccup: re-run first): compare `gh pr diff <N> --name-only` against the base
+PR's files. `merge --base` does the same check for a base with collapsed PRs. Use `--skip-collapse-check` only after
+confirming the base PR's diff on GitHub really has PR #N's changes.
+
+A push that fails with "fetched but never brought into local <branch>" means
+origin has commits you haven't integrated (git's --force-if-includes): pull or
+cherry-pick them, don't force past it.
+
 ### 7. Maintenance
 
 ```bash
 gh-stack delete        # remove a branch from the stack (re-parents children)
 gh-stack split         # cut a stack into two at a branch
+gh-stack join <b>      # splice an existing branch/PR into the stack (--above <b>, --dry-run)
 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
@@ -249,7 +384,7 @@ needed.
 - **Never force-pushes trunk.**
 - **Metadata is local and never committed:** per-stack files under
   `.git/.gh-stack/` plus git branch config. Inspect it via `gh-stack stacks
---json`, not by reading the store. (`gh-stack doctor` migrates the old v2
+  --json`, not by reading the store. (`gh-stack doctor` migrates the old v2
   `.git/gh-stack-metadata.json` monolith.)
 
 ## Don'ts

package/src/types.ts

@@ -59,11 +59,71 @@ export interface Snapshot {
   baseTip?: string;
 }
 
-// Resume state for restack --resume
+/**
+ * One step of a restack/sync/join run, appended to the run's action log as it
+ * happens (#15), so an interrupted run can say what it finished and what's left.
+ */
+export interface RunLogEntry {
+  at: string; // ISO 8601
+  branch: string;
+  action:
+    | "rebased" // rebased onto `onto`
+    | "up-to-date" // already on its parent: nothing to rebase
+    | "rebase-declined"
+    | "pushed"
+    | "push-failed"
+    | "push-declined"
+    | "push-held" // not pushed: its parent isn't on origin at the commit it sits on
+    | "local-only"; // no remote and no PR: left for `submit`
+  onto?: string;
+  detail?: string;
+}
+
+/** A rebase that has started but not been seen to finish (a conflict stop, or a kill). */
+export interface InFlightRebase {
+  branch: string;
+  onto: string; // ref the branch is being rebased onto
+  onto_sha: string; // that ref's tip when the rebase started
+  pre_tip: string; // the branch's tip before the rebase (what `git rebase --abort` restores)
+  /** The `--onto` upstream (`git rebase --onto <onto> <boundary> <branch>`); null for a plain `git rebase <onto>`. */
+  boundary: string | null;
+}
+
+/** Bumped when RestackState changes shape; a file with another version is refused, not upgraded. */
+export const RUN_STATE_VERSION = 2;
+
+/**
+ * The saved state of a restack/sync/join run, at `.git/.gh-stack/restack-state.json`.
+ * Written when the run starts and after every step, and kept after it finishes
+ * (`finished_at` set) so `restack --resume` can report a completed run.
+ */
 export interface RestackState {
-  current_index: number;
+  version: typeof RUN_STATE_VERSION;
+  /** What started the run: "restack", "sync", "join" or "restack --onto". */
+  command: string;
   stack_name: string;
+  /** Branches the run covers, parents before children. */
   chain: string[];
+  /**
+   * Branches in `chain` with only their push left: never rebased by the run
+   * (restack's trunk-parented roots, sync's root) or already rebased by it.
+   */
+  push_only: string[];
+  /** First branch in `chain` not yet processed. */
+  current_index: number;
+  /** The rebase in progress at `chain[current_index]`, if any. */
+  rebase: InFlightRebase | null;
+  /** Branches whose rebase was declined: not done, so a resume offers them again. */
+  declined: string[];
+  /**
+   * The run's push decision. `--resume` keeps it (a local-only run stays
+   * local) unless the resume passes --push/--no-push (#36, #39).
+   */
+  push: boolean;
+  started_at: string;
+  /** Set once every step, pushes included, is done. */
+  finished_at: string | null;
+  log: RunLogEntry[];
 }
 
 // PR info from GitHub API