aicp-cli 0.3.0__py3-none-any.whl

aicp/__init__.py

@@ -0,0 +1,18 @@
+"""aicp — AI commit + push, with a git-verified result summary.
+
+Python port of ``~/scripts/bin/aicp``. See ``aicp.contracts`` for the frozen
+interface shared across this package's modules.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # The distribution name, not the import name — these differ: `aicp` was
+    # taken on PyPI in 2021 by an unrelated project. Reading it from installed
+    # metadata keeps pyproject.toml the single source of truth, so the version
+    # in `--version` and the `--config` title can never drift from the release.
+    __version__ = version("aicp-cli")
+except PackageNotFoundError:  # pragma: no cover - unbuilt checkout
+    __version__ = "0+unknown"

aicp/_keyreader.py

@@ -0,0 +1,210 @@
+"""Raw single-key input, with a guaranteed non-blocking degradation.
+
+Three surfaces, one module: POSIX ``termios``/``tty``, Windows ``msvcrt``,
+and — the one that actually matters for correctness — a plain line-oriented
+fallback whenever stdin is not a TTY.
+
+**Why the fallback is load-bearing.** aicp runs in CI, in a pipe, and under
+this project's own pytest suite, none of which have a terminal to press keys
+on. A menu that reached for raw mode there would either raise (no ``fileno``)
+or, far worse, block forever waiting for a keystroke that is never coming.
+So :func:`is_interactive` is checked BEFORE any raw-mode call, and
+:func:`read_line` treats EOF as "quit" rather than as something to wait on.
+:func:`read_key` mirrors that: on a non-TTY it reads a line and maps it, and
+an empty read is ``"quit"``, never a wait.
+
+Key names returned are semantic (``up``/``down``/``left``/``right``/
+``enter``/``quit``/``reset``/``yes``/``other``) so the menu never sees a byte.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from collections.abc import Callable, Iterator
+from typing import IO
+
+__all__ = ["is_interactive", "key_session", "pending", "read_key", "read_line"]
+
+#: What :func:`key_session` hands back: call it to wrap a prompt that reads a
+#: typed line, which needs the line discipline the session suspends.
+_Typed = Callable[[], "contextlib.AbstractContextManager[None]"]
+
+# Windows sends arrows as a two-byte sequence introduced by one of these.
+_WIN_PREFIXES = ("\x00", "\xe0")
+_WIN_ARROWS = {"H": "up", "P": "down", "K": "left", "M": "right"}
+_VT_ARROWS = {"A": "up", "B": "down", "C": "right", "D": "left"}
+
+
+def is_interactive(stdin: IO[str] | None = None, stdout: IO[str] | None = None) -> bool:
+    """True only when BOTH streams are a real terminal.
+
+    Both, not either: a menu that repaints needs somewhere to draw as much as
+    it needs somewhere to read from, and a redirected stdout with a live
+    stdin still has no frame to walk the cursor back up through.
+    """
+    streams = (stdin or sys.stdin, stdout or sys.stdout)
+    try:
+        return all(s is not None and s.isatty() for s in streams)
+    except (AttributeError, ValueError, OSError):
+        return False
+
+
+def read_line(stdin: IO[str] | None = None) -> str | None:
+    """One stripped line, or ``None`` at EOF (never a block on a dead pipe)."""
+    stream = stdin or sys.stdin
+    try:
+        line = stream.readline()
+    except (OSError, ValueError):
+        return None
+    if line == "":
+        return None
+    return line.strip()
+
+
+def _classify(text: str) -> str:
+    """Map typed text from the non-raw path onto a semantic key name."""
+    lowered = text.strip().lower()
+    if lowered in ("", "q", "quit"):
+        return "quit"
+    return {
+        "up": "up", "k": "up",
+        "down": "down", "j": "down",
+        "left": "left", "h": "left",
+        "right": "right", "l": "right",
+        "r": "reset",
+        "y": "yes",
+    }.get(lowered, "enter" if lowered in ("enter", "\n") else "other")
+
+
+def _read_key_posix(stream: IO[str]) -> str:
+    import os
+    import termios
+    import tty
+
+    fd = stream.fileno()
+    saved = termios.tcgetattr(fd)
+    try:
+        # TCSANOW, not tty.setraw's TCSAFLUSH default: flushing discards
+        # typeahead, so a key pressed while the menu was still repainting
+        # would be silently swallowed rather than acted on next.
+        tty.setraw(fd, termios.TCSANOW)
+        ch = os.read(fd, 1).decode("utf-8", "replace")
+        if ch == "\x1b":
+            # An arrow is ESC [ X; a bare ESC is the user backing out. The
+            # follow-up bytes are already buffered by the terminal, so this
+            # read cannot hang on a real escape sequence.
+            rest = os.read(fd, 2).decode("utf-8", "replace")
+            return _VT_ARROWS.get(rest[-1:], "other") if rest.startswith("[") else "quit"
+    finally:
+        # Restoring the terminal is not optional and not only for the happy
+        # path: a shell left in -icanon -echo looks broken to whoever uses it
+        # next, so the restore is armed before raw mode is ever entered.
+        termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+    return _from_char(ch)
+
+
+def _read_key_windows() -> str:
+    import msvcrt
+
+    ch = msvcrt.getwch()
+    if ch in _WIN_PREFIXES:
+        return _WIN_ARROWS.get(msvcrt.getwch(), "other")
+    return _from_char(ch)
+
+
+def _from_char(ch: str) -> str:
+    if ch in ("\r", "\n", " "):
+        return "enter"
+    # Raw mode disables ISIG, so Ctrl+C arrives as a byte rather than a
+    # signal — cancelling a menu changed nothing and is not a failure.
+    if ch in ("q", "Q", "\x03", "\x04", ""):
+        return "quit"
+    if ch in ("r", "R"):
+        return "reset"
+    if ch in ("y", "Y"):
+        return "yes"
+    return "other"
+
+
+@contextlib.contextmanager
+def key_session(stdin: IO[str], stdout: IO[str]) -> Iterator[_Typed]:
+    """Hold the terminal in cbreak mode for a whole arrow-key session.
+
+    Raw mode per keypress leaves the terminal echoing **between** reads, and
+    a menu that animates spends real time between reads: a key pressed while
+    a frame is moving is echoed onto the screen by the terminal driver
+    itself, an Enter echoes a newline that pushes the whole frame down a
+    row, and every repaint after it walks the cursor up to the wrong place —
+    stacking a fresh header on screen for each one. That is the "hold Enter
+    and the panel multiplies" bug, and no amount of care in the drawing code
+    can fix it, because it is not the drawing code writing.
+
+    cbreak and not raw: ``tty.setraw`` also turns off output processing, and
+    a panel printed with no NL→CRNL translation comes out as a staircase.
+    cbreak touches the input side only — and leaves Ctrl+C a signal, which
+    the caller handles rather than reading as a byte.
+
+    Yields the context manager to wrap any prompt that reads a typed line:
+    :func:`read_line` needs the canonical mode this suspends.
+    """
+    if sys.platform == "win32" or not is_interactive(stdin, stdout):
+        yield contextlib.nullcontext
+        return
+    import termios
+    import tty
+
+    fd = stdin.fileno()
+    saved = termios.tcgetattr(fd)
+
+    @contextlib.contextmanager
+    def typed() -> Iterator[None]:
+        termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+        try:
+            yield
+        finally:
+            tty.setcbreak(fd, termios.TCSANOW)
+
+    try:
+        # TCSANOW, not setcbreak's TCSAFLUSH default: flushing discards
+        # typeahead, and a key pressed while the menu was still drawing is
+        # one the user meant, not one to swallow.
+        tty.setcbreak(fd, termios.TCSANOW)
+        yield typed
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, saved)
+
+
+def pending(stdin: IO[str]) -> bool:
+    """Whether a keypress is already waiting to be read.
+
+    An animation is time the menu is not listening, so it asks: with another
+    key already queued, the frames still to draw are ones nobody will look
+    at, and dropping them is what keeps a held-down key feeling immediate
+    instead of replaying a backlog of slides.
+    """
+    try:
+        if sys.platform == "win32":
+            import msvcrt
+
+            return msvcrt.kbhit()
+        import select
+
+        return bool(select.select([stdin], [], [], 0)[0])
+    except (AttributeError, ImportError, OSError, ValueError):
+        return False
+
+
+def read_key(stdin: IO[str] | None = None, stdout: IO[str] | None = None) -> str:
+    """One semantic key press. Falls back to a typed line on a non-TTY."""
+    stream = stdin or sys.stdin
+    if not is_interactive(stream, stdout):
+        line = read_line(stream)
+        return "quit" if line is None else _classify(line)
+    if sys.platform == "win32":
+        return _read_key_windows()
+    try:
+        return _read_key_posix(stream)
+    except (OSError, ValueError, ImportError):
+        line = read_line(stream)
+        return "quit" if line is None else _classify(line)

aicp/_skills_data/commit.md

@@ -0,0 +1,90 @@
+---
+description: Stage and commit all changes, grouped into logical Conventional Commits batches.
+model: sonnet
+effort: medium
+---
+
+# Commit
+
+Git commit current changes, split into logical batches if needed.
+
+## Project override (check FIRST)
+
+Skills/custom commands resolve **personal-over-project** on a name clash, so
+this global `/commit` shadows a project's own `.claude/commands/commit.md`. The
+global CLAUDE.md "same-name precedence" rule already requires deferring to the
+project version when one exists — honor it: if `.claude/commands/commit.md`
+exists in the project, READ it and follow it instead of this file (pass
+`$ARGUMENTS` through unchanged), and skip the rest of this file.
+
+Only when the project has **no** `commit.md` of its own: if `$ARGUMENTS` looks
+like an issue-tracker key (`[A-Z]+-[0-9]+`) or a `.../browse/<KEY>` URL AND the
+project defines `.claude/commands/commit-bug.md`, invoke `/commit-bug` with the
+original `$ARGUMENTS` and stop; otherwise fall through to the standard flow.
+
+## Workflow
+
+1. Run `git status` + `git diff --stat` to survey all uncommitted changes. Read full
+   diffs only where grouping is not already obvious from the path — a file whose
+   concern is ambiguous, or one you suspect spans concerns (step 6). Never open the
+   full diff of the whole worktree up front.
+2. **If any `.jsonl` files appear in the changes (modified, untracked, or staged), notify the user** — list the file(s), then skip them entirely and continue with all other commits as normal. Only perform git operations on `.jsonl` files (commit, discard, etc.) if the user explicitly names the file(s) and requests it.
+3. **If `.gitignore` or `.gitignore_global` has any changes (new file, modified, or deleted), commit them alone first** before any other batch.
+4. Group remaining changes into atomic batches — one concern per commit (feature code, tests, docs, config, etc.).
+5. **Before staging each batch**, check `git status` for any pre-existing staged files (left column `M`/`A`/`D`). If any staged file does not belong to the current batch, run `git restore --staged <file>` to pull it out of the index first — otherwise it will be swept into the commit unintentionally.
+6. For each file in a batch, decide the staging strategy:
+   - **All hunks belong to the same concern** → `git add <file>` (stage the whole file)
+   - **Hunks span multiple concerns** → stage only the relevant hunks via patch:
+     1. `git diff <file>` — capture the full diff
+     2. Extract only the hunk(s) belonging to this batch (preserve the file header lines and the correct `@@ … @@` context lines)
+     3. Write the partial patch to a temp file, then `git apply --cached <tmpfile>`
+     4. Commit; repeat for the remaining hunks in subsequent batches
+
+   Then write a compliant commit message and commit.
+
+If all changes form one coherent unit, make one commit. Never bundle unrelated changes.
+
+## Commit Message Format
+
+```text
+<type>[(<scope>)]: <description>
+
+[body]
+
+[footer(s)]
+```
+
+**Types:** `feat` `fix` `docs` `style` `refactor` `test` `perf` `build` `ci` `chore` `hotfix` `revert`
+
+Pick one from that list — **never invent a new type** (`update`, `remove`, `config`, `improve` are all invalid). No exact match → take the closest: source changed but behavior unchanged → `refactor`; source untouched (deps, generated files, moves, config) → `chore`.
+
+**Hard constraints on `<description>`:** max 50 characters; no trailing period; lowercase.
+
+**Body:** wrap at 72 characters per line.
+
+**Footer:** if the change relates to a tracked issue, add `Closes #<issue>` in the footer.
+
+> **Capitalization conflict:** Conventional Commits uses all-lowercase `description`; the seven-rules style capitalizes the first letter. Default here is lowercase — pick one per project and apply consistently.
+
+## Breaking Change Detection
+
+Before composing each commit message, scan the staged diff. Mark the commit with `!` after the type/scope **and** add a `BREAKING CHANGE:` footer if **any** of these apply:
+
+- **Schema rename/removal** — YAML/JSON/proto/GraphQL/TS-type fields renamed, removed, or restructured in a file other code/agents/scripts parse.
+- **Public API removal/rename** — exported function, class, slash command, agent, skill, plugin entry, or event template deleted or renamed.
+- **Required input change** — optional → required, or required param type changes incompatibly.
+- **Output format change** — stdout, return value, file format, or notification event payload changes in a way callers must adapt to.
+- **Config restructure** — `settings.json` / `manifest.txt` / `.env` keys renamed or removed when downstream consumers depend on them.
+
+Example:
+
+```text
+refactor(scope)!: short description
+
+Body explaining the change.
+
+BREAKING CHANGE: <one-line consequence summary>
+<details if needed; wrap at 72 chars>
+```
+
+If ambiguous, **ask the user** before committing: *"Is this change breaking for callers? (yes/no)"*

aicp/_skills_data/safe-git-push/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: safe-git-push
+description: Safely synchronize and push the current git branch. Always fetches before pushing, never uses `git pull`, never creates an accidental self-merge like "Merge remote-tracking branch 'origin/develop' into develop", preserves intentional cross-branch merge topology instead of flattening it with a blind rebase, and never force-pushes or rewrites shared history. Use this whenever a `git push` is needed, especially on a shared branch (develop/main) or after the remote may have moved.
+---
+
+# Safe Git Push
+
+Fetch → compare local vs. remote by ancestry → integrate only if it can be
+done without inventing a self-merge or flattening a real merge → push. All
+of that logic lives in `scripts/safe_push.py`; this file just explains when
+each branch of the decision runs and what to do with the result.
+
+## Run it
+
+```bash
+python3 scripts/safe_push.py
+# ambiguous remote (no upstream set, multiple remotes exist):
+python3 scripts/safe_push.py --remote origin
+```
+
+Exit code `0` = pushed, fast-forwarded, or already in sync (message says
+which). Exit code `1` = stopped without touching anything — read the
+`Safe push aborted: <reason>` line on stderr and handle it by hand.
+
+## Decision summary
+
+| Situation after fetch | What the script does |
+|---|---|
+| Remote branch doesn't exist yet | First push, `--set-upstream` |
+| Local == remote | Nothing to push, reports and exits |
+| Local strictly ahead | Push directly, no rebase/merge |
+| Local strictly behind | `git merge --ff-only`, then nothing to push |
+| Diverged, local history has a likely self-merge not yet pushed | **Stops** — won't guess whether to keep or drop it |
+| Diverged, otherwise | Backs up HEAD to a throwaway ref, `git rebase --rebase-merges=no-rebase-cousins <remote>` (preserves real cross-branch merges instead of flattening them), verifies the merge count and ancestry didn't change, then pushes |
+| Rebase conflicts | Aborts the rebase, restores the branch, reports the conflicting files, stops |
+| Push rejected (someone else pushed in between) | Re-fetches and re-analyzes, up to 2 retries, never force-pushes |
+| Remote says protected branch / permission denied | Stops, tells you to use the normal PR/MR flow |
+
+Never done, under any circumstance: `git pull`, a plain `git merge <remote-ref>`,
+`git push --force`/`-f`/`--force-with-lease`/`--all`/`--mirror`/`--tags`/`--no-verify`,
+`git reset --hard` on anything but the script's own just-created backup ref,
+`git stash`/`clean`/`commit`, or switching branches. If any of those turns out
+to be genuinely necessary, that's a deliberate follow-up task for you to run
+yourself, not something this skill does silently.
+
+## Known gaps (not automated — call out if they matter)
+
+- Doesn't verify a submodule gitlink you're pushing already exists on the
+  submodule's own remote. Rare; check manually if the diff touches submodules.
+- Doesn't try to auto-resolve rebase conflicts — always stops and hands them
+  back. Automating "safe" conflict resolution is exactly the kind of guess
+  this skill exists to avoid making.
+- Signed commits: rebasing recreates commits, so if `commit.gpgsign` is on,
+  git re-signs them as part of the rebase; the script doesn't add anything
+  beyond leaving that setting alone.

aicp/_skills_data/safe-git-push/scripts/safe_push.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Safe git push: fetch, analyze the graph, integrate only when it can't
+create an accidental self-merge or flatten intentional cross-branch merges,
+then push. See ../SKILL.md for the decision summary.
+
+Exit code 0 = pushed or already in sync. Exit code 1 = stopped (see stderr).
+Never uses: git pull, git merge <remote-ref> (plain), git push --force*/--all/
+--mirror/--tags/--no-verify, git reset --hard on anything but our own backup
+ref, git stash/clean/commit, or a branch/checkout switch.
+"""
+import argparse
+import re
+import subprocess
+import sys
+import time
+
+MAX_PUSH_RETRIES = 2
+
+
+def run(cmd, check=True):
+    p = subprocess.run(cmd, capture_output=True, text=True)
+    if check and p.returncode != 0:
+        raise RuntimeError(f"$ {' '.join(cmd)}\n{p.stderr.strip()}")
+    return p
+
+
+def run_ok(cmd):
+    return subprocess.run(cmd, capture_output=True, text=True).returncode == 0
+
+
+def stop(msg):
+    print(f"Safe push aborted: {msg}", file=sys.stderr)
+    print("No destructive git operation was performed; no shared history was rewritten.", file=sys.stderr)
+    sys.exit(1)
+
+
+def git_dir():
+    return run(["git", "rev-parse", "--git-dir"]).stdout.strip()
+
+
+def check_preconditions():
+    if not run_ok(["git", "rev-parse", "--is-inside-work-tree"]):
+        stop("not inside a git work tree.")
+
+    gd = git_dir()
+    import os
+    in_progress = [
+        name for name, path in {
+            "rebase (merge)": f"{gd}/rebase-merge",
+            "rebase (apply)": f"{gd}/rebase-apply",
+            "merge": f"{gd}/MERGE_HEAD",
+            "cherry-pick": f"{gd}/CHERRY_PICK_HEAD",
+            "revert": f"{gd}/REVERT_HEAD",
+            "bisect": f"{gd}/BISECT_LOG",
+        }.items() if os.path.exists(path)
+    ]
+    if in_progress:
+        stop(f"a {in_progress[0]} is already in progress. Resolve or abort it first.")
+
+    branch_p = subprocess.run(["git", "symbolic-ref", "--quiet", "--short", "HEAD"],
+                               capture_output=True, text=True)
+    if branch_p.returncode != 0:
+        stop("HEAD is detached; cannot safely guess which branch to push.")
+    branch = branch_p.stdout.strip()
+
+    dirty = run(["git", "status", "--porcelain"]).stdout.strip()
+    if dirty:
+        print("Note: working tree has uncommitted changes; they are never included "
+              "in a push and are left untouched.", file=sys.stderr)
+
+    if run(["git", "rev-parse", "--is-shallow-repository"]).stdout.strip() == "true":
+        print("Note: shallow repository; ancestry checks below may be incomplete.", file=sys.stderr)
+
+    return branch
+
+
+def resolve_remote(branch, remote_override):
+    if remote_override:
+        return remote_override
+    remote = run(["git", "config", "--get", f"branch.{branch}.remote"], check=False).stdout.strip()
+    if remote:
+        return remote
+    remotes = [r for r in run(["git", "remote"]).stdout.splitlines() if r.strip()]
+    if len(remotes) == 1:
+        return remotes[0]
+    if not remotes:
+        stop("no git remote configured.")
+    stop(f"branch '{branch}' has no upstream and multiple remotes exist ({', '.join(remotes)}); "
+         f"rerun with --remote <name>.")
+
+
+def fetch_branch(remote, branch):
+    p = subprocess.run(
+        ["git", "fetch", remote, f"refs/heads/{branch}:refs/remotes/{remote}/{branch}"],
+        capture_output=True, text=True,
+    )
+    if p.returncode == 0:
+        return True  # remote branch exists and was fetched
+    if "couldn't find remote ref" in p.stderr or "not found" in p.stderr.lower():
+        return False  # remote branch doesn't exist yet -> first push
+    stop(f"fetch from '{remote}' failed:\n{p.stderr.strip()}")
+
+
+def is_ancestor(maybe_ancestor, ref):
+    return run_ok(["git", "merge-base", "--is-ancestor", maybe_ancestor, ref])
+
+
+SELF_MERGE_RE = re.compile(
+    r"^Merge (remote-tracking )?branch '([^']*/)?{branch}'(\s+of\s+\S+)?\s+into\s+{branch}$"
+)
+
+
+def find_suspicious_self_merge(remote_ref, branch):
+    log = run(["git", "log", "--merges", "--format=%H\t%s", f"{remote_ref}..HEAD"]).stdout
+    pat = re.compile(SELF_MERGE_RE.pattern.format(branch=re.escape(branch)))
+    for line in log.splitlines():
+        sha, _, subject = line.partition("\t")
+        if pat.match(subject.strip()):
+            return sha, subject.strip()
+    return None
+
+
+def push(remote, branch, set_upstream):
+    cmd = ["git", "-c", "push.followTags=false", "push"]
+    if set_upstream:
+        cmd.append("--set-upstream")
+    cmd += [remote, f"HEAD:refs/heads/{branch}"]
+    return subprocess.run(cmd, capture_output=True, text=True)
+
+
+def verify_pushed(remote, branch):
+    local_sha = run(["git", "rev-parse", "HEAD"]).stdout.strip()
+    remote_sha = run(["git", "ls-remote", remote, f"refs/heads/{branch}"]).stdout.split()[0]
+    if local_sha != remote_sha:
+        stop(f"push verification failed: remote is {remote_sha[:10]}, local HEAD is {local_sha[:10]}.")
+    return local_sha
+
+
+def attempt(branch, remote, has_upstream):
+    remote_exists = fetch_branch(remote, branch)
+
+    if not remote_exists:
+        p = push(remote, branch, set_upstream=True)
+        if p.returncode != 0:
+            handle_push_failure(p.stderr)
+        sha = verify_pushed(remote, branch)
+        print(f"Safe push completed (first push).\nBranch: {branch}\nRemote: {remote}/{branch}\n"
+              f"Remote HEAD: {sha}")
+        return
+
+    remote_ref = f"{remote}/{branch}"
+    local_sha = run(["git", "rev-parse", "HEAD"]).stdout.strip()
+    remote_sha = run(["git", "rev-parse", remote_ref]).stdout.strip()
+
+    if local_sha == remote_sha:
+        print(f"Already synchronized with {remote_ref}. Nothing to push.")
+        return
+
+    if is_ancestor(remote_ref, "HEAD"):
+        pass  # local ahead -> fall through to push directly
+    elif is_ancestor("HEAD", remote_ref):
+        run(["git", "merge", "--ff-only", remote_ref])
+        print(f"Fast-forwarded to {remote_ref}. Nothing to push.")
+        return
+    else:
+        integrate_diverged(remote_ref, branch)
+
+    p = push(remote, branch, set_upstream=not has_upstream)
+    if p.returncode != 0:
+        handle_push_failure(p.stderr)
+    sha = verify_pushed(remote, branch)
+    print(f"Safe push completed.\nBranch: {branch}\nRemote: {remote_ref}\nRemote HEAD: {sha}")
+
+
+def integrate_diverged(remote_ref, branch):
+    suspicious = find_suspicious_self_merge(remote_ref, branch)
+    if suspicious:
+        sha, subject = suspicious
+        stop(f"local history contains a likely self-merge ({sha[:10]} \"{subject}\") "
+             f"not yet pushed. Not touching it automatically — review it by hand.")
+
+    old_head = run(["git", "rev-parse", "HEAD"]).stdout.strip()
+    backup_ref = f"refs/backup/safe-push/{branch}-{int(time.time())}"
+    run(["git", "update-ref", backup_ref, old_head])
+
+    old_merge_count = len(run(["git", "log", "--merges", "--format=%H", f"{remote_ref}..HEAD"]).stdout.splitlines())
+
+    p = subprocess.run(["git", "rebase", "--rebase-merges=no-rebase-cousins", remote_ref],
+                        capture_output=True, text=True)
+    if p.returncode != 0:
+        conflicts = run(["git", "diff", "--name-only", "--diff-filter=U"], check=False).stdout.strip()
+        run(["git", "rebase", "--abort"], check=False)
+        stop("rebase hit conflicts and was aborted; branch restored to its pre-rebase state.\n"
+             f"Conflicting files:\n{conflicts}\nResolve manually, then rerun.")
+
+    ok = is_ancestor(remote_ref, "HEAD") and not run_ok(["test", "-d", f"{git_dir()}/rebase-merge"])
+    new_merge_count = len(run(["git", "log", "--merges", "--format=%H", f"{remote_ref}..HEAD"]).stdout.splitlines())
+    if not ok or new_merge_count != old_merge_count:
+        run(["git", "reset", "--hard", backup_ref])
+        stop("post-rebase verification failed (remote not an ancestor, or merge topology changed); "
+             f"restored from backup ref {backup_ref}.")
+
+    run(["git", "update-ref", "-d", backup_ref])
+
+
+PROTECTED_MARKERS = ("protected branch", "permission denied", "not allowed to push")
+
+
+def handle_push_failure(stderr):
+    low = stderr.lower()
+    if any(m in low for m in PROTECTED_MARKERS):
+        stop(f"remote rejected the push (protected branch):\n{stderr.strip()}\n"
+             "Use the repository's normal PR/MR workflow instead.")
+    if "non-fast-forward" in low or "fetch first" in low or "rejected" in low:
+        raise Retry(stderr)
+    stop(f"push failed:\n{stderr.strip()}")
+
+
+class Retry(Exception):
+    pass
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--remote", help="Override the remote to use (needed when ambiguous).")
+    args = ap.parse_args()
+
+    branch = check_preconditions()
+    has_upstream = bool(run(["git", "config", "--get", f"branch.{branch}.merge"], check=False).stdout.strip())
+    remote = resolve_remote(branch, args.remote)
+
+    for attempt_no in range(MAX_PUSH_RETRIES + 1):
+        try:
+            attempt(branch, remote, has_upstream)
+            return
+        except Retry as e:
+            if attempt_no == MAX_PUSH_RETRIES:
+                stop(f"push kept getting rejected (remote changed concurrently) after "
+                     f"{MAX_PUSH_RETRIES + 1} attempts:\n{e}")
+            print(f"Push rejected (remote changed); re-fetching and re-analyzing "
+                  f"(attempt {attempt_no + 2}/{MAX_PUSH_RETRIES + 1})...", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except RuntimeError as e:
+        stop(str(e))