assertion-cli 0.5.12__tar.gz → 0.5.14__tar.gz

{assertion_cli-0.5.12 → assertion_cli-0.5.14}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: assertion-cli
-Version: 0.5.12
+Version: 0.5.14
 Summary: CLI for the Assertion API
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: pydantic>=2.12.5
-Requires-Dist: python-dotenv>=1.0
 Requires-Dist: typer>=0.24.1
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
@@ -18,7 +17,8 @@ CLI for the Assertion API.
 
 ## Usage
 
-The CLI currently targets a local backend at `http://localhost:8000`.
+The CLI targets `https://app.tryassertion.com` by default; set
+`ASSERTION_BASE_URL` (e.g. `http://localhost:8000`) to point at another backend.
 
 Run locally from the workspace:
 
@@ -34,12 +34,13 @@ uv tool install --reinstall assertion-cli  # upgrade in place
 ```
 
 The CLI package declares all of its direct runtime dependencies. At the moment
-that set is `httpx`, `pydantic`, `python-dotenv`, and `typer`.
+that set is `httpx`, `pydantic`, and `typer`.
 
 After installation:
 
 ```bash
 asrt install                           # one-time onboarding: write skill files, AGENTS.md/CLAUDE.md pointer, .gitignore
+asrt login                             # authenticate this repo (generate a token at Settings → Authentication)
 asrt session start                     # per work session: record the diff base (current HEAD)
 asrt new                               # reset local run state for a fresh session
 asrt stacks
@@ -50,6 +51,32 @@ asrt verify                            # submit final verification (non-blocking
 asrt verify-status                     # one-shot poll; loop with your own sleep until terminal
 ```
 
+## Authentication
+
+`asrt login` stores your API token in a global, user-level file —
+`~/.assertion/credentials.json` (mode `0600`) — keyed by the repo's path:
+
+```json
+{ "version": 1, "repos": { "/abs/path/to/repo": "alk_..." } }
+```
+
+Run it from inside the repo it should authenticate. It validates the token and
+confirms the repo's `origin` remote is connected to a stack in the token's
+workspace before saving, so each repo can target a different workspace. Because
+entries are keyed by path, moving or renaming the repo folder means logging in
+again (which adds a new entry). `asrt logout` removes the current repo's entry;
+`asrt whoami` shows which token is in effect.
+
+Token resolution at call time, in order:
+
+1. the entry for the current repo path in `~/.assertion/credentials.json`;
+2. the `ASSERTION_API_TOKEN` environment variable (a backup for CI, or repos
+   with no remote that `asrt login` won't store);
+
+with a clear "run `asrt login`" error when neither is present. The API base URL
+defaults to `https://app.tryassertion.com`; override it with `ASSERTION_BASE_URL`
+for a local backend.
+
 ## Publishing a new version
 
 1. **Bump the version** in `cli/pyproject.toml`.

{assertion_cli-0.5.12 → assertion_cli-0.5.14}/README.md

@@ -4,7 +4,8 @@ CLI for the Assertion API.
 
 ## Usage
 
-The CLI currently targets a local backend at `http://localhost:8000`.
+The CLI targets `https://app.tryassertion.com` by default; set
+`ASSERTION_BASE_URL` (e.g. `http://localhost:8000`) to point at another backend.
 
 Run locally from the workspace:
 
@@ -20,12 +21,13 @@ uv tool install --reinstall assertion-cli  # upgrade in place
 ```
 
 The CLI package declares all of its direct runtime dependencies. At the moment
-that set is `httpx`, `pydantic`, `python-dotenv`, and `typer`.
+that set is `httpx`, `pydantic`, and `typer`.
 
 After installation:
 
 ```bash
 asrt install                           # one-time onboarding: write skill files, AGENTS.md/CLAUDE.md pointer, .gitignore
+asrt login                             # authenticate this repo (generate a token at Settings → Authentication)
 asrt session start                     # per work session: record the diff base (current HEAD)
 asrt new                               # reset local run state for a fresh session
 asrt stacks
@@ -36,6 +38,32 @@ asrt verify                            # submit final verification (non-blocking
 asrt verify-status                     # one-shot poll; loop with your own sleep until terminal
 ```
 
+## Authentication
+
+`asrt login` stores your API token in a global, user-level file —
+`~/.assertion/credentials.json` (mode `0600`) — keyed by the repo's path:
+
+```json
+{ "version": 1, "repos": { "/abs/path/to/repo": "alk_..." } }
+```
+
+Run it from inside the repo it should authenticate. It validates the token and
+confirms the repo's `origin` remote is connected to a stack in the token's
+workspace before saving, so each repo can target a different workspace. Because
+entries are keyed by path, moving or renaming the repo folder means logging in
+again (which adds a new entry). `asrt logout` removes the current repo's entry;
+`asrt whoami` shows which token is in effect.
+
+Token resolution at call time, in order:
+
+1. the entry for the current repo path in `~/.assertion/credentials.json`;
+2. the `ASSERTION_API_TOKEN` environment variable (a backup for CI, or repos
+   with no remote that `asrt login` won't store);
+
+with a clear "run `asrt login`" error when neither is present. The API base URL
+defaults to `https://app.tryassertion.com`; override it with `ASSERTION_BASE_URL`
+for a local backend.
+
 ## Publishing a new version
 
 1. **Bump the version** in `cli/pyproject.toml`.

{assertion_cli-0.5.12 → assertion_cli-0.5.14}/api.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import os
+from pathlib import Path
 from typing import Any, TypeVar
 
 import httpx
 import typer
-from dotenv import find_dotenv, load_dotenv
 from pydantic import BaseModel, ValidationError
 
+from credentials import API_TOKEN_ENV, resolve_token
+from git import find_git_root_or_none
 from models import (
     CheckpointResponse,
     DecisionResponse,
@@ -24,28 +26,35 @@ T = TypeVar("T", bound=BaseModel)
 # local backend (or self-hosted users) override with ASSERTION_BASE_URL.
 DEFAULT_BASE_URL = "https://app.tryassertion.com"
 DEFAULT_CHECKPOINT_TIMEOUT_SECONDS = 300.0
-API_TOKEN_ENV = "ASSERTION_API_TOKEN"
-
-# Walk up from cwd looking for a .env so the user can drop their token in the
-# repo root once and forget it. override=False means a real shell `export`
-# still wins over the file — useful for CI.
-_dotenv_path = find_dotenv(usecwd=True)
-if _dotenv_path:
-    load_dotenv(_dotenv_path, override=False)
 
 
 def _base_url() -> str:
     return os.environ.get("ASSERTION_BASE_URL", DEFAULT_BASE_URL)
 
 
+def _resolve_token() -> str | None:
+    """Token for the current repo, else the shell env-var backup, else None.
+
+    The stored credential (keyed by the exact current git root) is primary; a
+    real `export ASSERTION_API_TOKEN` only fills in when no entry matches — e.g.
+    in CI, or a repo that was moved/renamed and never re-authenticated.
+    """
+    token = resolve_token(find_git_root_or_none(Path.cwd()))
+    if token:
+        return token
+    env_token = (os.environ.get(API_TOKEN_ENV) or "").strip()
+    return env_token or None
+
+
 def _auth_headers() -> dict[str, str]:
-    token = (os.environ.get(API_TOKEN_ENV) or "").strip()
+    token = _resolve_token()
     if not token:
+        repo_root = find_git_root_or_none(Path.cwd())
+        where = f" for {repo_root}" if repo_root else ""
         typer.echo(
-            f"Missing {API_TOKEN_ENV}. Generate a token at Settings → Authentication "
-            "in the dashboard, then save it in a .env at your repo root:\n\n"
-            f"  echo '{API_TOKEN_ENV}=alk_...' >> .env\n\n"
-            "(Or export it in your shell.)",
+            f"No saved Assertion token{where}. Run `asrt login` to authenticate "
+            "this repo (if you moved or renamed the folder, log in again).\n"
+            f"Alternatively, export {API_TOKEN_ENV} in your shell as a backup.",
             err=True,
         )
         raise typer.Exit(code=1)
@@ -68,8 +77,16 @@ def _summarize_error(response: httpx.Response) -> str:
 
 
 class AssertionClient:
-    def __init__(self) -> None:
+    def __init__(self, *, token: str | None = None) -> None:
         self.base_url = _base_url()
+        # An explicit token lets `asrt login` validate a credential before it is
+        # saved; otherwise headers resolve from the store / env-var backup.
+        self._token_override = token.strip() if token else None
+
+    def _headers(self) -> dict[str, str]:
+        if self._token_override:
+            return {"Authorization": f"Bearer {self._token_override}"}
+        return _auth_headers()
 
     def _request(
         self,
@@ -81,7 +98,7 @@ class AssertionClient:
         **kwargs: Any,
     ) -> T:
         url = f"{self.base_url}{path}"
-        headers = {**_auth_headers(), **kwargs.pop("headers", {})}
+        headers = {**self._headers(), **kwargs.pop("headers", {})}
         try:
             response = httpx.request(
                 method, url, timeout=timeout, headers=headers, **kwargs
@@ -119,7 +136,7 @@ class AssertionClient:
         **kwargs: Any,
     ) -> DecisionResponse:
         url = f"{self.base_url}{path}"
-        headers = {**_auth_headers(), **kwargs.pop("headers", {})}
+        headers = {**self._headers(), **kwargs.pop("headers", {})}
         try:
             response = httpx.request(
                 method, url, timeout=timeout, headers=headers, **kwargs
@@ -145,7 +162,7 @@ class AssertionClient:
 
         url = f"{self.base_url}/api/v0/agent/stacks"
         try:
-            response = httpx.get(url, timeout=10.0, headers=_auth_headers())
+            response = httpx.get(url, timeout=10.0, headers=self._headers())
             response.raise_for_status()
         except httpx.HTTPStatusError as exc:
             summary = _summarize_error(exc.response)

{assertion_cli-0.5.12 → assertion_cli-0.5.14}/assertion_cli.egg-info/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: assertion-cli
-Version: 0.5.12
+Version: 0.5.14
 Summary: CLI for the Assertion API
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: pydantic>=2.12.5
-Requires-Dist: python-dotenv>=1.0
 Requires-Dist: typer>=0.24.1
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
@@ -18,7 +17,8 @@ CLI for the Assertion API.
 
 ## Usage
 
-The CLI currently targets a local backend at `http://localhost:8000`.
+The CLI targets `https://app.tryassertion.com` by default; set
+`ASSERTION_BASE_URL` (e.g. `http://localhost:8000`) to point at another backend.
 
 Run locally from the workspace:
 
@@ -34,12 +34,13 @@ uv tool install --reinstall assertion-cli  # upgrade in place
 ```
 
 The CLI package declares all of its direct runtime dependencies. At the moment
-that set is `httpx`, `pydantic`, `python-dotenv`, and `typer`.
+that set is `httpx`, `pydantic`, and `typer`.
 
 After installation:
 
 ```bash
 asrt install                           # one-time onboarding: write skill files, AGENTS.md/CLAUDE.md pointer, .gitignore
+asrt login                             # authenticate this repo (generate a token at Settings → Authentication)
 asrt session start                     # per work session: record the diff base (current HEAD)
 asrt new                               # reset local run state for a fresh session
 asrt stacks
@@ -50,6 +51,32 @@ asrt verify                            # submit final verification (non-blocking
 asrt verify-status                     # one-shot poll; loop with your own sleep until terminal
 ```
 
+## Authentication
+
+`asrt login` stores your API token in a global, user-level file —
+`~/.assertion/credentials.json` (mode `0600`) — keyed by the repo's path:
+
+```json
+{ "version": 1, "repos": { "/abs/path/to/repo": "alk_..." } }
+```
+
+Run it from inside the repo it should authenticate. It validates the token and
+confirms the repo's `origin` remote is connected to a stack in the token's
+workspace before saving, so each repo can target a different workspace. Because
+entries are keyed by path, moving or renaming the repo folder means logging in
+again (which adds a new entry). `asrt logout` removes the current repo's entry;
+`asrt whoami` shows which token is in effect.
+
+Token resolution at call time, in order:
+
+1. the entry for the current repo path in `~/.assertion/credentials.json`;
+2. the `ASSERTION_API_TOKEN` environment variable (a backup for CI, or repos
+   with no remote that `asrt login` won't store);
+
+with a clear "run `asrt login`" error when neither is present. The API base URL
+defaults to `https://app.tryassertion.com`; override it with `ASSERTION_BASE_URL`
+for a local backend.
+
 ## Publishing a new version
 
 1. **Bump the version** in `cli/pyproject.toml`.

{assertion_cli-0.5.12 → assertion_cli-0.5.14}/assertion_cli.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 README.md
 api.py
 bundle.py
+credentials.py
 git.py
 link.py
 main.py
@@ -17,13 +18,14 @@ templates/AGENTS.md
 templates/SKILL.md
 templates/__init__.py
 tests/test_api.py
+tests/test_auth.py
 tests/test_bundle.py
+tests/test_credentials.py
 tests/test_decision.py
 tests/test_git.py
 tests/test_install.py
 tests/test_link.py
 tests/test_main.py
-tests/test_new.py
 tests/test_prompt.py
 tests/test_session.py
 tests/test_session_start.py

{assertion_cli-0.5.12 → assertion_cli-0.5.14}/assertion_cli.egg-info/requires.txt

@@ -1,6 +1,5 @@
 httpx>=0.28.1
 pydantic>=2.12.5
-python-dotenv>=1.0
 typer>=0.24.1
 
 [test]

{assertion_cli-0.5.12 → assertion_cli-0.5.14}/assertion_cli.egg-info/top_level.txt

@@ -1,6 +1,7 @@
 api
 assertion_cli_templates
 bundle
+credentials
 git
 link
 main

{assertion_cli-0.5.12 → assertion_cli-0.5.14}/bundle.py

@@ -6,24 +6,21 @@ from models import MetadataPayload
 
 ASSERTION_DIR_NAME = ".assertion"
 DIFF_ARCHIVE_PATH = "git.diff"
-UNCOMMITTED_DIFF_ARCHIVE_PATH = "uncommitted.diff"
+REVIEW_DIFF_ARCHIVE_PATH = "review.diff"
 METADATA_ARCHIVE_PATH = f"{ASSERTION_DIR_NAME}/metadata.json"
 PROMPTS_ARCHIVE_PATH = f"{ASSERTION_DIR_NAME}/prompts"
 CHECKPOINT_ARCHIVE_PATH = f"{ASSERTION_DIR_NAME}/checkpoint"
 
 
 def _metadata_wire_json(metadata: MetadataPayload) -> str:
-    """Serialize metadata for the bundle, remapping `base_sha` → `head_sha`.
+    """Serialize metadata for the bundle.
 
-    The CLI stores the diff base as `base_sha` because that matches what the
-    field means from the CLI's perspective (the foundation the diff builds
-    on). The backend reads it as `head_sha` because after its `git checkout`
-    that SHA literally is the clone's HEAD. Same value, different name per
-    side; the remap lives here so neither side has to know about the other's
-    perspective.
+    `clone_sha` is the remote commit the backend sandbox checks out, so it is
+    emitted as `head_sha` on the wire. `base_sha` is the verification base
+    (where the user wants to start verifying from) and is emitted as-is.
     """
     payload = metadata.model_dump()
-    payload["head_sha"] = payload.pop("base_sha", None)
+    payload["head_sha"] = payload.pop("clone_sha", None)
     return json.dumps(payload, indent=2) + "\n"
 
 
@@ -31,7 +28,7 @@ def build_bundle(
     *,
     metadata: MetadataPayload,
     diff_text: str,
-    uncommitted_diff_text: str,
+    review_diff_text: str,
     prompts_text: str,
     checkpoint_text: str,
 ) -> bytes:
@@ -41,5 +38,5 @@ def build_bundle(
         zf.writestr(PROMPTS_ARCHIVE_PATH, prompts_text)
         zf.writestr(CHECKPOINT_ARCHIVE_PATH, checkpoint_text)
         zf.writestr(DIFF_ARCHIVE_PATH, diff_text)
-        zf.writestr(UNCOMMITTED_DIFF_ARCHIVE_PATH, uncommitted_diff_text)
+        zf.writestr(REVIEW_DIFF_ARCHIVE_PATH, review_diff_text)
     return buf.getvalue()

assertion_cli-0.5.14/credentials.py

@@ -0,0 +1,120 @@
+"""Global, user-level token store at ``~/.assertion/credentials.json``.
+
+The store is a map of canonicalized git-root path -> API token, so each repo
+resolves to its own workspace token:
+
+    {"version": 1, "repos": {"/abs/path/to/repo": "alk_..."}}
+
+This module is deliberately git-free and pure stdlib — callers pass in the repo
+root (resolved via ``git.py``) and handle their own error reporting. Token
+resolution precedence (repo entry first, then the env-var backup) lives in
+``api.py``; this module only owns on-disk reads and writes.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+API_TOKEN_ENV = "ASSERTION_API_TOKEN"
+
+CREDENTIALS_FILE_NAME = "credentials.json"
+CREDENTIALS_VERSION = 1
+
+
+def assertion_home() -> Path:
+    """Directory holding global Assertion credentials (``~/.assertion``)."""
+    return Path.home() / ".assertion"
+
+
+def credentials_path() -> Path:
+    return assertion_home() / CREDENTIALS_FILE_NAME
+
+
+def _empty_store() -> dict:
+    return {"version": CREDENTIALS_VERSION, "repos": {}}
+
+
+def load_store() -> dict:
+    """Return the credentials store, tolerating a missing or corrupt file.
+
+    A malformed file is treated as empty rather than crashing every command —
+    the user can re-run ``asrt login`` to repair it.
+    """
+    path = credentials_path()
+    if not path.exists():
+        return _empty_store()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError, ValueError):
+        return _empty_store()
+    if not isinstance(data, dict):
+        return _empty_store()
+    data.setdefault("version", CREDENTIALS_VERSION)
+    if not isinstance(data.get("repos"), dict):
+        data["repos"] = {}
+    return data
+
+
+def _repo_key(repo_root: Path) -> str:
+    """Canonical store key for a repo root (absolute, symlinks resolved)."""
+    return str(repo_root.resolve())
+
+
+def _write_store(store: dict) -> Path:
+    home = assertion_home()
+    home.mkdir(parents=True, exist_ok=True)
+    try:
+        home.chmod(0o700)
+    except OSError:
+        pass
+    path = credentials_path()
+    path.write_text(json.dumps(store, indent=2) + "\n", encoding="utf-8")
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+    return path
+
+
+def save_token(token: str, *, repo_root: Path) -> Path:
+    """Persist ``token`` for ``repo_root`` and return the credentials file path."""
+    store = load_store()
+    store["repos"][_repo_key(repo_root)] = token
+    return _write_store(store)
+
+
+def remove_token(*, repo_root: Path) -> bool:
+    """Delete the entry for ``repo_root``. Return ``True`` if one was removed."""
+    store = load_store()
+    key = _repo_key(repo_root)
+    if key in store["repos"]:
+        del store["repos"][key]
+        _write_store(store)
+        return True
+    return False
+
+
+def resolve_token(repo_root: Path | None) -> str | None:
+    """Return the stored token for ``repo_root`` (exact path match), else ``None``.
+
+    No fuzzy or parent-path matching: a moved or never-authenticated repo simply
+    misses, and the caller falls back to the env-var backup.
+    """
+    if repo_root is None:
+        return None
+    token = load_store()["repos"].get(_repo_key(repo_root))
+    return token or None
+
+
+def describe_source(repo_root: Path | None) -> str | None:
+    """Describe where the active token comes from, in resolution order.
+
+    Returns a human phrase for ``whoami``, or ``None`` when nothing resolves.
+    """
+    if repo_root is not None and resolve_token(repo_root) is not None:
+        return f"the saved token for {_repo_key(repo_root)}"
+    if (os.environ.get(API_TOKEN_ENV) or "").strip():
+        return f"the {API_TOKEN_ENV} environment variable"
+    return None

{assertion_cli-0.5.12 → assertion_cli-0.5.14}/git.py

@@ -26,7 +26,12 @@ def run_git_command(
     return completed.stdout if preserve_stdout else completed.stdout.strip()
 
 
-def find_git_root(start_path: Path) -> Path:
+def find_git_root_or_none(start_path: Path) -> Path | None:
+    """Return the repo root for *start_path*, or ``None`` if it isn't in a repo.
+
+    Token resolution must degrade gracefully (to the env-var backup) outside a
+    git repo, so it needs a non-fatal variant of ``find_git_root``.
+    """
     completed = subprocess.run(
         ["git", "rev-parse", "--show-toplevel"],
         cwd=start_path,
@@ -35,10 +40,61 @@ def find_git_root(start_path: Path) -> Path:
         check=False,
     )
     if completed.returncode != 0:
-        exit_with_error("Current directory is not inside a git repository.")
+        return None
     return Path(completed.stdout.strip())
 
 
+def find_git_root(start_path: Path) -> Path:
+    root = find_git_root_or_none(start_path)
+    if root is None:
+        exit_with_error("Current directory is not inside a git repository.")
+    return root
+
+
+def _parse_github_full_name(url: str) -> str | None:
+    """Reduce a git remote URL to its GitHub ``owner/repo`` full name.
+
+    Handles the three common origin forms and returns ``None`` when the URL has
+    no ``owner/repo`` tail:
+
+        git@github.com:acme/mvp.git        -> acme/mvp
+        https://github.com/acme/mvp.git    -> acme/mvp
+        ssh://git@github.com/acme/mvp.git  -> acme/mvp
+    """
+    text = url.strip()
+    if not text:
+        return None
+
+    if "://" in text:
+        # scheme://[user@]host/owner/repo — drop scheme + host.
+        path = text.split("://", 1)[1]
+        path = path.split("/", 1)[1] if "/" in path else ""
+    elif ":" in text and ("/" not in text or text.index(":") < text.index("/")):
+        # scp-like: [user@]host:owner/repo (colon precedes any path slash).
+        path = text.split(":", 1)[1]
+    else:
+        path = text
+
+    path = path.removesuffix(".git").strip("/")
+    parts = [p for p in path.split("/") if p]
+    if len(parts) < 2:
+        return None
+    return f"{parts[-2]}/{parts[-1]}"
+
+
+def current_repo_full_name(repo_root: Path) -> str | None:
+    """Return the repo's GitHub ``owner/repo``, or ``None`` if it has no origin.
+
+    Used by ``asrt login`` to match the current checkout against the workspace's
+    stacks (whose ``repo`` field is the GitHub full name).
+    """
+    try:
+        url = run_git_command(repo_root, ["remote", "get-url", "origin"])
+    except RuntimeError:
+        return None
+    return _parse_github_full_name(url)
+
+
 def get_head_sha(repo_root: Path) -> str:
     try:
         return run_git_command(repo_root, ["rev-parse", "HEAD"])
@@ -59,7 +115,8 @@ def get_upstream_ref(repo_root: Path) -> str | None:
     # 1. Configured upstream (git branch -u).
     try:
         return run_git_command(
-            repo_root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]
+            repo_root,
+            ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"],
         )
     except RuntimeError:
         pass
@@ -83,15 +140,16 @@ def get_upstream_ref(repo_root: Path) -> str | None:
         merged = run_git_command(
             repo_root,
             [
-                "branch", "-r", "--merged", "HEAD",
+                "branch",
+                "-r",
+                "--merged",
+                "HEAD",
                 "--format=%(refname:short)",
             ],
         )
         ancestors = [r for r in merged.splitlines() if r]
         if ancestors:
-            return run_git_command(
-                repo_root, ["merge-base", "HEAD", *ancestors]
-            )
+            return run_git_command(repo_root, ["merge-base", "HEAD", *ancestors])
     except RuntimeError:
         pass
 
@@ -132,6 +190,55 @@ def get_merge_base(repo_root: Path, upstream: str) -> str:
         )
 
 
+def is_ancestor(repo_root: Path, maybe_ancestor: str, descendant: str) -> bool:
+    """Return True if *maybe_ancestor* is an ancestor of *descendant*."""
+    try:
+        run_git_command(
+            repo_root, ["merge-base", "--is-ancestor", maybe_ancestor, descendant]
+        )
+        return True
+    except RuntimeError:
+        return False
+
+
+def get_remote_ancestor(repo_root: Path, sha: str) -> str | None:
+    """Return the newest remote commit that is an ancestor of *sha*.
+
+    Uses local remote-tracking refs so this works offline. Returns ``None``
+    when no remote-tracking ref contains an ancestor of *sha*.
+    """
+    try:
+        merged = run_git_command(
+            repo_root,
+            ["branch", "-r", "--merged", sha, "--format=%(refname:short)"],
+        )
+    except RuntimeError:
+        return None
+
+    candidates = [r for r in merged.splitlines() if r]
+    if not candidates:
+        return None
+
+    newest_ref: str | None = None
+    newest_ts = -1
+    for ref in candidates:
+        try:
+            ts = int(run_git_command(repo_root, ["log", "-1", "--format=%ct", ref]))
+        except (RuntimeError, ValueError):
+            continue
+        if ts > newest_ts:
+            newest_ts = ts
+            newest_ref = ref
+
+    if newest_ref is None:
+        return None
+
+    try:
+        return run_git_command(repo_root, ["merge-base", sha, newest_ref])
+    except RuntimeError:
+        return None
+
+
 def get_head_branch(repo_root: Path) -> str | None:
     """Return the current branch name, or None if HEAD is detached."""
     try: