assertion-cli 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

{assertion_cli-0.2.0.dist-info → assertion_cli-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertion-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: CLI for the Assertion API
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown

assertion_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+api.py,sha256=6RuyOoZrsBTY_51XA60iHwkYJ6nqME0CrmDgGaEbWzk,6901
+bundle.py,sha256=O616zO-SY66J0v2d1NAr3S7cshSmUIAUiYX_sI_dMYo,1515
+git.py,sha256=nxIdwy4i9pQ-40BnFO4_sLOdQK3zUHsYG17cmXZj8uE,4010
+link.py,sha256=bfH0MhkeTFGbOSJbSvuuw3ilGX3akyvjvCw25AP_fz8,643
+main.py,sha256=igQOML1A6WlSFD8SWM5P7WxnuwsWxMMvwp7knxj4DpA,20759
+models.py,sha256=ApnfCO7CF5Nfdy5-ho7U-YRLWM-C3421fAT7GXa4Y30,2269
+session.py,sha256=3oe3GbAaA2ynjk-2DFsLvwlFUMwHNnUmTKkBrQo_8IE,6507
+assertion_cli_templates/ACTIVATION.md,sha256=5Z63TiInCe_vJEhOkqiKb1S4LRJHKy4Wx-c5yUb8p8M,1608
+assertion_cli_templates/SKILL.md,sha256=zE1QB-vRIzqxHAvCZI1VsE0S2fb7cWb_ynPwzATg9no,13260
+assertion_cli_templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+assertion_cli-0.3.0.dist-info/METADATA,sha256=aGRIOYEii33yusuUfejxJCHsf93cxs7xDDy13n8sIes,1712
+assertion_cli-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+assertion_cli-0.3.0.dist-info/entry_points.txt,sha256=LgwuPLZEIk-4sD7ghGVRQOhm3PG8sPVozMRxrihwMgU,34
+assertion_cli-0.3.0.dist-info/top_level.txt,sha256=xbZYH9xQOa99z-Vbkc2Xp6h8oUR97DVlyczy8H4ZuFc,64
+assertion_cli-0.3.0.dist-info/RECORD,,

assertion_cli_templates/ACTIVATION.md

@@ -8,7 +8,7 @@ This repo uses the Assertion CLI (`asrt`) to track user intent and verify your w
 Both files are byte-identical. Read whichever your agent loads (or either one directly). In brief, follow these three rules for every conversation:
 
 1. **Every user message:** call `asrt prompt "<exact text of the message>"` before doing any other work for that turn. This is the verifier's source of truth for what the user asked for and how their direction evolves. Apply to every user turn, not just the first.
-2. **Checkpoint at trajectory-feedback moments**, not on every small change. Use `asrt checkpoint "<summary>"` — the CLI auto-resolves the stack from this repo's GitHub origin on the first call and auto-continues the session on subsequent calls. A whole feature build is a handful of checkpoints, not one per file.
+2. **Checkpoint at trajectory-feedback moments**, not on every small change. On the first checkpoint of a session, run `asrt stacks`, pick the stack that fits this repo and the work (use the stack's `repo`, `name`, `description`, plus folder/branch/README signals), then run `asrt checkpoint --stack <id> "<summary>"`. Subsequent checkpoints in the same session don't need `--stack` — `asrt checkpoint "<summary>"` auto-continues. A whole feature build is a handful of checkpoints, not one per file.
 3. **Verify at completion** with `asrt verify`. If feedback requires changes, iterate and re-verify — do **not** drop back into the checkpoint loop. Once verify is clean, open a PR with `gh pr create` and include the session URL (from `asrt get-link`) in the body.
 
 Do not open a PR without a clean `asrt verify`.

assertion_cli_templates/SKILL.md

@@ -14,11 +14,11 @@ This skill is operational, not advisory. Treat each rule as a hard requirement u
 Before any `asrt` call:
 
 - You are inside a git repository.
-- The repo has at least one remote-tracking ref that shares history with `HEAD` (the CLI uses the latest such commit as the diff base for checkpoint/verify; local-only commits on top flow through as part of the diff). `asrt prompt` does not require this.
+- `asrt init` has been run in this repo. It records the current HEAD as the diff base that every checkpoint/verify diffs against, and installs the skill files you are reading right now. If `asrt checkpoint` or `asrt verify` errors with "No diff base recorded", run `asrt init` and retry.
 
-No `asrt init` is needed — the CLI creates `.assertion/` on first use. Treat `.assertion/metadata.json` and `.assertion/prompts` as internal state owned by the CLI. Do not create, edit, or delete those files manually — use `asrt prompt` to append to the prompts log.
+Treat `.assertion/metadata.json`, `.assertion/prompts`, and `.assertion/base_sha` as internal state owned by the CLI. Do not create, edit, or delete those files manually — use `asrt prompt` to append to the prompts log.
 
-`asrt stacks` is read-only and lists available verification stack IDs. Run it once per session before your first checkpoint so you can pick a stack ID; do not hardcode IDs from memory.
+`asrt stacks` is read-only and lists every verification stack in the user's workspace, along with the repo each is configured for. Run it once per session before your first checkpoint so you can pick a stack ID; do not hardcode IDs from memory.
 
 ---
 
@@ -59,20 +59,20 @@ This applies to **every user turn**, not just the first. It applies even when th
 
 **Form:**
 
-Every checkpoint:
+The first checkpoint of a session needs a stack ID; subsequent ones don't:
+
 ```
-asrt checkpoint "<what you built and what you decided>"
+asrt checkpoint --stack <STACK_ID> "<what you built and decided>"   # first checkpoint
+asrt checkpoint "<what you built and decided>"                       # 2nd+ checkpoints
 ```
 
-You don't need a flag to distinguish "first" from "subsequent" — the CLI does the right thing:
-- No session exists yet → start a new one. The CLI picks the stack by matching the repo's GitHub `owner/name` (from `git remote get-url origin`) against the stacks attached to this repo.
-- A session already exists → continue it.
-
-If no stack is attached to this repo on the very first checkpoint, the command fails with a clear message telling the user to attach one in the Assertion web app. If multiple stacks are attached, it tells you to pass `--stack <id>` to disambiguate.
+How the CLI decides:
+- `.assertion/metadata.json` doesn't exist yet → no session. You must pass `--stack <id>`. The CLI errors with a clear message if you don't.
+- A session already exists → continue it. Don't pass `--stack` (it would overwrite the in-flight session).
 
-Flags exist for explicit intent, but you normally don't need them:
+Flags exist for explicit intent:
 - `--continue` — fail fast if no session exists (otherwise behaves identically to no flag when a session does exist).
-- `--stack <id>` — force a brand-new session against a specific stack, overwriting any existing one. Only pass this if you deliberately want to abandon the current session.
+- `--stack <id>` — anchor the new session to a specific stack. **Required on the first checkpoint, rejected once a session exists.** The stack is locked at session creation; re-anchoring would create a split verification record, so the CLI errors if you try. Only the user can reset a session (by clearing `.assertion/`).
 
 Use checkpoint messages to summarize substantive progress and decisions since the previous checkpoint — not a changelog of every line touched.
 
@@ -82,41 +82,31 @@ Use checkpoint messages to summarize substantive progress and decisions since th
 - If failed: treat the feedback as authoritative for the next slice of work, address it, then checkpoint again. Do not push toward verify with failing feedback unaddressed.
 - Optionally, after a failed checkpoint, record your sentiment with `asrt decision --yes <checkpoint-id>` (you agree with the feedback) or `asrt decision --no <checkpoint-id>` (you disagree). Do not call `decision` for successful checkpoints.
 
-### Stack selection — handled by the CLI
-
-Stack selection is **enforced by the CLI**, not by you. When you run `asrt checkpoint "..."` (no `--stack` flag), the CLI:
-
-1. Runs `git remote get-url origin` and normalizes to `owner/name`
-2. Calls the backend, fetches every stack in the user's workspace, and matches by the stack's `repo` field
-3. Picks the single match → starts the session against it
-4. If zero or multiple match, exits non-zero with a clear, user-facing error
+### Stack selection — your judgment, not the CLI's
 
-You don't need to do the matching yourself or pass `--stack`. Just call `asrt checkpoint "..."`.
+**You pick the stack.** Before the first checkpoint, run `asrt stacks` to see every stack in the user's workspace. Each line includes the stack's `id`, `name`, `description`, and the `repo` it's configured for. Pick the one that best fits this repo and the work in flight, then pass it as `--stack <id>` on the first checkpoint.
 
-### When `asrt checkpoint` fails because no stack is available
-
-This is the most common failure. The CLI distinguishes three cases — your response is the same shape in all of them:
-
-| CLI error starts with | Meaning |
-|---|---|
-| `No verification stacks exist in this workspace yet.` | User has never set up any stacks. |
-| `No verification stack is attached to this repo (...)` | Stacks exist but none are bound to this repo. |
-| `Multiple stacks are attached to ...` | Two or more stacks match; CLI asks for `--stack <id>`. |
+Signals to use, in roughly decreasing order of strength:
 
-**For the first two:** the user has to take an action in the Assertion web app. Your response:
+1. **Stack `repo` field vs. this repo's identity.** A stack whose `repo` matches the local checkout (folder name, `git remote -v` if present, `git config --get remote.origin.url`, the `name` in `package.json` / `pyproject.toml` / `Cargo.toml`, the top heading in `README.md`) is almost always the right choice.
+2. **Stack `name` / `description` vs. the work.** When more than one stack could plausibly fit the repo, pick the one whose name/description best matches the primary deliverable (e.g., "PR Code Quality" for refactors, "Security Review" for auth/permissions work, "Docs Audit" for documentation passes). The user's prompt log is your guide to what they actually asked for.
+3. **Branch name.** A branch named `feat/billing-…` against a stack named `Billing QA` is a strong signal.
 
-1. Tell the user the error verbatim. The CLI already wrote the right message.
-2. **Keep the work moving on your side.** You can continue editing files and implementing what the user asked for. Verification is the gate before opening a PR — not a gate on writing code.
-3. Keep calling `asrt prompt "..."` on every new user turn. The prompt log accumulates in `.assertion/prompts` and is *not* lost when checkpoint fails — once the user attaches a stack, the next successful `asrt checkpoint "..."` ships every prompt logged so far in its bundle.
-4. When the user says they've attached a stack (or asks you to retry), call `asrt checkpoint "<what you built so far>"` again. The CLI will resolve the stack this time and start the session with the full prompt history already in the bundle.
+If none of the stacks plausibly fit this repo, surface that to the user verbatim — do not guess. They likely need to attach a stack in the Assertion web app first. Keep recording prompts; the prompt log persists and ships in the bundle once the user picks a stack and you successfully checkpoint.
 
-**Do not** try to work around the missing stack by guessing a stack ID, hardcoding one from another repo, or picking the wrong one with `--stack`. Repo-binding is the user's signal that the stack is configured for this codebase; bypassing it creates a verification session in the wrong context.
+When you pass `--stack`, briefly state which stack you chose and why ("Picked stack `abc123` — its `repo` matches and the description fits the auth work the user described"). That gives the user one chance to redirect before the session is anchored.
 
-**For the third case (multiple matches):** the CLI's error lists the candidates. Pick the one whose name/description best fits the primary deliverable (code review, security, docs, perf) and pass `asrt checkpoint --stack <id> "..."`. State your choice briefly so the user can correct you.
+**Never** hardcode a stack ID from memory, copy one from a different repo, or pick one whose `repo` field clearly points elsewhere just to get a session started. A wrong stack creates a verification record in the wrong context, which is worse than no session at all.
 
-### Optional: confirm before you start
+### When `asrt checkpoint` errors
 
-If you want to know which stack the CLI *would* pick before running checkpoint (e.g., the work is about to be long and you want to fail-fast on configuration), call `asrt stacks` and look for the line with `[repo: <current-repo-owner/name>]`. You don't have to — `asrt checkpoint` does this internally — but it's available as a read-only check.
+| CLI error starts with | What it means | What to do |
+|---|---|---|
+| `No session exists yet and no --stack given.` | First checkpoint of a fresh `.assertion/`, but you didn't pick a stack. | Run `asrt stacks`, pick one using the signals above, pass `--stack <id>`. |
+| `This session is already anchored to a stack.` | You passed `--stack` after a session was already created. The CLI locks the stack at session creation. | Drop the `--stack` flag and re-run `asrt checkpoint "<message>"`. |
+| `ERROR: Unknown stack '<id>'.` | The `--stack` you passed is not in the workspace. | Re-run `asrt stacks` (the list may have changed) and pass a valid id. |
+| `No diff base recorded for this repo.` | `asrt init` wasn't run. | Run `asrt init` and retry. |
+| `ERROR: No active session to continue.` | You passed `--continue` but there is no session. | Drop `--continue` and pass `--stack <id>` to start one. |
 
 ---
 
@@ -164,13 +154,14 @@ done
 ## Quick reference
 
 ```
-asrt prompt "<message>"             # every user turn, before anything else
-asrt stacks                         # optional: list stacks attached to this repo
-asrt checkpoint "..."               # at trajectory moments — auto-starts or continues
-asrt decision --yes|--no <ckpt-id>  # optional, on failed checkpoints only
-asrt verify                         # submit verification (non-blocking)
-asrt verify-status                  # one-shot poll; loop with your own sleep
-asrt get-link                       # retrieve the last session URL
+asrt prompt "<message>"                       # every user turn, before anything else
+asrt stacks                                   # list every stack — read once before first checkpoint
+asrt checkpoint --stack <id> "..."            # first checkpoint of a session
+asrt checkpoint "..."                         # subsequent checkpoints — auto-continues
+asrt decision --yes|--no <ckpt-id>            # optional, on failed checkpoints only
+asrt verify                                   # submit verification (non-blocking)
+asrt verify-status                            # one-shot poll; loop with your own sleep
+asrt get-link                                 # retrieve the last session URL
 ```
 
 ## Environment

bundle.py

@@ -1,4 +1,5 @@
 import io
+import json
 import zipfile
 
 from models import MetadataPayload
@@ -10,6 +11,21 @@ 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`.
+
+    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.
+    """
+    payload = metadata.model_dump()
+    payload["head_sha"] = payload.pop("base_sha", None)
+    return json.dumps(payload, indent=2) + "\n"
+
+
 def build_bundle(
     *,
     metadata: MetadataPayload,
@@ -19,7 +35,7 @@ def build_bundle(
 ) -> bytes:
     buf = io.BytesIO()
     with zipfile.ZipFile(buf, mode="w", compression=zipfile.ZIP_DEFLATED) as zf:
-        zf.writestr(METADATA_ARCHIVE_PATH, metadata.model_dump_json(indent=2) + "\n")
+        zf.writestr(METADATA_ARCHIVE_PATH, _metadata_wire_json(metadata))
         zf.writestr(PROMPTS_ARCHIVE_PATH, prompts_text)
         zf.writestr(CHECKPOINT_ARCHIVE_PATH, checkpoint_text)
         zf.writestr(DIFF_ARCHIVE_PATH, diff_text)

git.py

@@ -37,73 +37,6 @@ def find_git_root(start_path: Path) -> Path:
     return Path(completed.stdout.strip())
 
 
-def get_diff_base_sha(repo_root: Path) -> str:
-    """Return the SHA the verifier should diff against — i.e. the most recent
-    commit reachable from BOTH local HEAD and some `refs/remotes/*` ref.
-
-    The verifier clones from GitHub and runs `git checkout <head_sha>` (see
-    backend/repo_analysis/clone.py). That checkout fails for any commit that
-    only exists locally — which is exactly what Codex Cloud produces when its
-    agent autocommits before `asrt checkpoint`. By picking the latest commit
-    that's on origin AND reachable from HEAD, the checkout always succeeds;
-    any local-only commits on top of that base flow through as part of the
-    diff (see `get_uncommitted_diff`), so the verifier still sees the full
-    state the agent built.
-
-    When HEAD itself is on a remote-tracking ref (no local commits),
-    `git merge-base HEAD <ref>` returns HEAD, so this collapses to the old
-    behavior with no diff growth.
-    """
-    try:
-        remote_refs = run_git_command(
-            repo_root, ["for-each-ref", "--format=%(refname:short)", "refs/remotes"]
-        )
-    except RuntimeError as exc:
-        exit_with_error(f"Failed to inspect remote refs: {exc}")
-
-    refs = [
-        ref for ref in remote_refs.splitlines() if ref and not ref.endswith("/HEAD")
-    ]
-    if not refs:
-        exit_with_error(
-            "No remote-tracking branches found. The verifier needs a commit "
-            "on origin to apply the diff onto — push at least one branch "
-            "(and `git fetch`) before running this command."
-        )
-
-    candidate_shas: list[str] = []
-    for ref in refs:
-        completed = subprocess.run(
-            ["git", "merge-base", "HEAD", ref],
-            cwd=repo_root,
-            capture_output=True,
-            text=True,
-            check=False,
-        )
-        if completed.returncode == 0:
-            sha = completed.stdout.strip()
-            if sha:
-                candidate_shas.append(sha)
-
-    if not candidate_shas:
-        exit_with_error(
-            "HEAD has no commits in common with any remote-tracking branch. "
-            "Push the branch (or its parent commits) to origin and retry."
-        )
-
-    best_sha = candidate_shas[0]
-    best_ts = -1
-    for sha in candidate_shas:
-        try:
-            ts = int(run_git_command(repo_root, ["log", "-1", "--format=%ct", sha]))
-        except (RuntimeError, ValueError):
-            continue
-        if ts > best_ts:
-            best_ts = ts
-            best_sha = sha
-    return best_sha
-
-
 def get_head_sha(repo_root: Path) -> str:
     try:
         return run_git_command(repo_root, ["rev-parse", "HEAD"])
@@ -120,40 +53,6 @@ def get_head_branch(repo_root: Path) -> str | None:
     return name if name and name != "HEAD" else None
 
 
-def get_origin_github_repo(repo_root: Path) -> str | None:
-    """Return the current repo's GitHub `owner/name` from origin, or None if not parseable.
-
-    Accepts the common remote URL forms:
-      git@github.com:owner/name(.git)?
-      https://github.com/owner/name(.git)?
-      ssh://git@github.com/owner/name(.git)?
-    """
-    try:
-        url = run_git_command(repo_root, ["remote", "get-url", "origin"]).strip()
-    except RuntimeError:
-        return None
-    if not url:
-        return None
-
-    if url.startswith("git@github.com:"):
-        path = url[len("git@github.com:") :]
-    elif url.startswith("ssh://git@github.com/"):
-        path = url[len("ssh://git@github.com/") :]
-    elif url.startswith("https://github.com/"):
-        path = url[len("https://github.com/") :]
-    elif url.startswith("http://github.com/"):
-        path = url[len("http://github.com/") :]
-    else:
-        return None
-
-    path = path.rstrip("/")
-    if path.endswith(".git"):
-        path = path[: -len(".git")]
-    if path.count("/") != 1 or not all(path.split("/")):
-        return None
-    return path
-
-
 def _build_untracked_diff(repo_root: Path, rel_path: str) -> str:
     completed = subprocess.run(
         [

main.py

@@ -5,6 +5,7 @@ import re
 from datetime import datetime, timezone
 from pathlib import Path
 
+import httpx
 import typer
 
 from api import AssertionClient
@@ -12,21 +13,23 @@ from bundle import build_bundle
 from git import (
     exit_with_error,
     find_git_root,
-    get_diff_base_sha,
     get_head_branch,
+    get_head_sha,
     get_uncommitted_diff,
 )
 from link import load_link, save_link
 from models import CheckpointResponse, SessionStatus, render_stack_list
 from session import (
     ASSERTION_DIR_NAME,
+    BASE_SHA_FILE_NAME,
     METADATA_FILE_NAME,
     PROMPTS_FILE_NAME,
     append_checkpoint_entry,
     continue_session,
     load_existing_session,
+    read_init_base_sha,
     start_new_session,
-    update_metadata_head,
+    update_metadata_anchor,
 )
 
 app = typer.Typer(help="Assertion CLI")
@@ -194,11 +197,26 @@ def init() -> None:
     the skill and knows to call `asrt`. `asrt checkpoint` refreshes the skill files on each
     run so they stay aligned with the installed CLI; `CLAUDE.md` / `AGENTS.md` are only
     touched here, never by checkpoint, so they're safe to track in git.
+
+    Also records the current HEAD SHA as the diff base for all future checkpoint/verify
+    calls in this repo. The base is what the backend `git checkout`s against before
+    applying the diff — capturing it once at init means later commands don't need to
+    rediscover it (which previously broke in sandboxes with no remote-tracking refs).
     """
     repo_root = find_git_root(Path.cwd())
     _refresh_skill_files(repo_root)
     _apply_activation_blocks(repo_root)
     _ensure_gitignore_excludes_assertion(repo_root)
+
+    base_sha = get_head_sha(repo_root)
+    assertion_dir = repo_root / ASSERTION_DIR_NAME
+    assertion_dir.mkdir(exist_ok=True)
+    base_sha_path = assertion_dir / BASE_SHA_FILE_NAME
+    base_sha_path.write_text(base_sha + "\n", encoding="utf-8")
+    typer.echo(
+        f"Recorded diff base {base_sha[:12]} → {base_sha_path.relative_to(repo_root)}"
+    )
+
     typer.echo("")
     typer.echo("The coding agent will now follow the Assertion workflow:")
     typer.echo('  - asrt prompt "<msg>" on every user turn')
@@ -234,7 +252,7 @@ def checkpoint(
     stack: str | None = typer.Option(
         None,
         "--stack",
-        help="Force a new session against this stack ID. Overwrites any existing session.",
+        help="Stack ID for a new session. Required on the first checkpoint; rejected once a session exists.",
     ),
     continue_session_flag: bool = typer.Option(
         False,
@@ -247,11 +265,12 @@ def checkpoint(
 ) -> None:
     """Record a checkpoint.
 
-    With no flag, the CLI auto-continues the existing session if one is present,
-    otherwise starts a new session against the stack attached to this repo's
-    GitHub origin. Use `--continue` to fail fast when no session exists, or
-    `--stack <id>` to force a brand-new session (destructive — replaces any
-    in-flight session).
+    First checkpoint of a session requires `--stack <id>` — the agent picks
+    the stack from `asrt stacks` using its own judgment (folder name, branch,
+    code, README, etc.). Once a session exists, the stack is locked: pass no
+    flag (auto-continues) or `--continue` (fails fast if no session exists).
+    Passing `--stack` on a later checkpoint is rejected — sessions cannot be
+    re-anchored mid-flight.
     """
     if stack and continue_session_flag:
         typer.echo("ERROR: --stack and --continue are mutually exclusive.", err=True)
@@ -266,35 +285,43 @@ def checkpoint(
     _refresh_skill_files(repo_root)
 
     existing_metadata_path = repo_root / ASSERTION_DIR_NAME / METADATA_FILE_NAME
+    session_exists = existing_metadata_path.exists()
 
-    if continue_session_flag or (stack is None and existing_metadata_path.exists()):
-        # Either the caller asked to continue explicitly, OR they passed no
-        # flag and a session already exists (2nd+ checkpoint of the same
-        # session). In both cases continue rather than starting fresh — the
-        # alternative would silently destroy an in-flight session. To force a
-        # new session, pass --stack <id> or clear .assertion/ first (the
-        # post-verify prompt offers to do this).
+    if stack and session_exists:
+        # The stack is locked once a session is anchored to it. The agent
+        # should never re-anchor — a wrong-stack mid-session creates a split
+        # verification record. The user is the only one who resets sessions.
+        exit_with_error(
+            "This session is already anchored to a stack. Sessions cannot be "
+            "re-anchored mid-flight — drop the `--stack` flag and re-run "
+            '`asrt checkpoint "<message>"` to continue. The anchored stack '
+            "is recorded in .assertion/metadata.json."
+        )
+
+    if continue_session_flag or session_exists:
         ctx, metadata = continue_session(start_path=Path.cwd())
     else:
-        from session import resolve_stack_id_for_repo
-
-        resolved_stack = stack or resolve_stack_id_for_repo(repo_root)
-        ctx, metadata = start_new_session(
-            start_path=Path.cwd(), stack_id=resolved_stack
-        )
+        if stack is None:
+            exit_with_error(
+                "No session exists yet and no --stack given. Run `asrt stacks` "
+                "to see available stacks, pick one whose name/description fits "
+                "the work, then run:\n"
+                '  asrt checkpoint --stack <STACK_ID> "<progress message>"'
+            )
+        ctx, metadata = start_new_session(start_path=Path.cwd(), stack_id=stack)
 
     stack_id = metadata.stack_id
     assert stack_id is not None
 
     append_checkpoint_entry(ctx.checkpoint_path, message)
-    # `head_sha` here is the diff base — the latest commit on origin that's
-    # also reachable from local HEAD. Backend uses it as the checkout target
-    # before applying the diff; sending the actual local HEAD would break
-    # when the agent has uncommitted-to-origin commits (e.g. Codex Cloud).
-    base_sha = get_diff_base_sha(ctx.repo_root)
+    # Base SHA is whatever `asrt init` recorded for this repo. Backend uses
+    # it as the checkout target before applying the diff. Pinning it at init
+    # time (instead of rediscovering per command) means sandboxes without
+    # remote-tracking refs — e.g. Codex Cloud — still work.
+    base_sha = read_init_base_sha(ctx.assertion_dir)
     head_branch = get_head_branch(ctx.repo_root)
     diff_text = get_uncommitted_diff(ctx.repo_root, base_sha)
-    metadata = update_metadata_head(
+    metadata = update_metadata_anchor(
         ctx.metadata_path, metadata, base_sha, head_branch=head_branch
     )
 
@@ -342,17 +369,34 @@ def _load_verify_session_id(assertion_dir: Path) -> str:
     return content
 
 
+def _decode_screenshot(uri: str) -> tuple[bytes, str]:
+    """Resolve a screenshot reference to (image bytes, file extension).
+
+    The backend may hand back either an inline ``data:`` URI (legacy format)
+    or an http(s) download URL pointing at the files proxy (current format,
+    e.g. ``.../api/v0/files/download/<token>``). Support both so a format
+    change on the backend doesn't break status reporting.
+    """
+    if uri.startswith("data:") and "," in uri:
+        header, b64data = uri.split(",", 1)
+        ext = "jpeg" if "jpeg" in header else "png"
+        return base64.b64decode(b64data), ext
+
+    response = httpx.get(uri, timeout=30.0, follow_redirects=True)
+    response.raise_for_status()
+    content_type = response.headers.get("content-type", "").lower()
+    is_jpeg = "jpeg" in content_type or uri.lower().endswith((".jpg", ".jpeg"))
+    return response.content, "jpeg" if is_jpeg else "png"
+
+
 def _write_screenshots(
     assertion_dir: Path, session_id: str, screenshots: list[str]
 ) -> Path:
     screenshot_dir = assertion_dir / "screenshots" / session_id
     screenshot_dir.mkdir(parents=True, exist_ok=True)
     for idx, uri in enumerate(screenshots):
-        _, b64data = uri.split(",", 1)
-        ext = "jpeg" if "jpeg" in uri.split(",")[0] else "png"
-        (screenshot_dir / f"screenshot_{idx:03d}.{ext}").write_bytes(
-            base64.b64decode(b64data)
-        )
+        data, ext = _decode_screenshot(uri)
+        (screenshot_dir / f"screenshot_{idx:03d}.{ext}").write_bytes(data)
     return screenshot_dir
 
 
@@ -374,11 +418,12 @@ def verify(
     ctx, metadata = load_existing_session(Path.cwd())
     stack_id = metadata.stack_id
     assert stack_id is not None
-    # See checkpoint() for why we send the diff base rather than local HEAD.
-    base_sha = get_diff_base_sha(ctx.repo_root)
+    # See checkpoint() for why the base is the SHA `asrt init` recorded,
+    # not local HEAD.
+    base_sha = read_init_base_sha(ctx.assertion_dir)
     head_branch = get_head_branch(ctx.repo_root)
     diff_text = get_uncommitted_diff(ctx.repo_root, base_sha)
-    metadata = update_metadata_head(
+    metadata = update_metadata_anchor(
         ctx.metadata_path, metadata, base_sha, head_branch=head_branch
     )
 
@@ -451,8 +496,20 @@ def verify_status(
 
     terminal = payload.status in {SessionStatus.SUCCEEDED, SessionStatus.FAILED}
     screenshot_count = len(payload.screenshots)
+    screenshots_saved = False
     if terminal and payload.screenshots:
-        _write_screenshots(ctx.assertion_dir, session_id, payload.screenshots)
+        # Saving screenshots must never block the verdict. A backend format
+        # change or a transient download failure should degrade to a warning,
+        # not swallow a `succeeded`/`failed` status the caller is waiting on.
+        try:
+            _write_screenshots(ctx.assertion_dir, session_id, payload.screenshots)
+            screenshots_saved = True
+        except Exception as exc:  # noqa: BLE001 - never let screenshots hide the verdict
+            typer.echo(
+                f"warning: could not save screenshots ({exc}); "
+                "the verdict below is unaffected.",
+                err=True,
+            )
 
     if json_output:
         typer.echo(
@@ -473,7 +530,7 @@ def verify_status(
             typer.echo(payload.message)
         if payload.summary:
             typer.echo(f"\nSummary:\n{payload.summary}")
-        if terminal and payload.screenshots:
+        if screenshots_saved:
             typer.echo(
                 f"\nScreenshots ({screenshot_count}) saved to "
                 f".assertion/screenshots/{session_id}/"

models.py

@@ -62,11 +62,22 @@ class ErrorResponse(BaseModel):
 
 
 class MetadataPayload(BaseModel):
+    """Local on-disk schema for `.assertion/metadata.json`.
+
+    `base_sha` is the diff base (the commit `asrt init` recorded; the commit
+    the backend checks out before applying the diff). In the bundle sent to
+    the backend it is remapped to `head_sha` for wire compatibility — from
+    the backend's perspective, after `git checkout <sha>`, that SHA IS its
+    HEAD, so the name reads correctly on the consumer side. Locally we keep
+    `base_sha` because it matches what the CLI stores (`.assertion/base_sha`)
+    and what the value represents from the CLI's perspective.
+    """
+
     model_config = ConfigDict(extra="allow")
 
     session_id: str
     stack_id: str | None = None
-    head_sha: str | None = None
+    base_sha: str | None = None
     head_branch: str | None = None
 
 

session.py

@@ -6,8 +6,6 @@ from api import AssertionClient
 from git import (
     exit_with_error,
     find_git_root,
-    get_diff_base_sha,
-    get_origin_github_repo,
 )
 from models import MetadataPayload, SessionContext, render_stack_list
 
@@ -15,13 +13,35 @@ ASSERTION_DIR_NAME = ".assertion"
 PROMPTS_FILE_NAME = "prompts"
 CHECKPOINT_FILE_NAME = "checkpoint"
 METADATA_FILE_NAME = "metadata.json"
+BASE_SHA_FILE_NAME = "base_sha"
+
+
+def read_init_base_sha(assertion_dir: Path) -> str:
+    """Return the diff base SHA recorded by `asrt init`.
+
+    Exits with a clear error if init hasn't been run or the file is empty.
+    The base SHA is the commit the backend `git checkout`s against before
+    applying the diff, so every checkpoint/verify must have it.
+    """
+    path = assertion_dir / BASE_SHA_FILE_NAME
+    if not path.exists():
+        exit_with_error(
+            "No diff base recorded for this repo. Run `asrt init` first — "
+            "it captures the HEAD SHA that checkpoint/verify diff against."
+        )
+    content = path.read_text(encoding="utf-8").strip()
+    if not content:
+        exit_with_error(
+            f"{path.name} is empty. Re-run `asrt init` to record the diff base."
+        )
+    return content
 
 
 def _require_repo_ready(start_path: Path) -> Path:
     repo_root = find_git_root(start_path)
-    # Fail fast here if no remote-reachable base exists. Result is discarded
-    # — callers re-compute at diff time, which is cheap.
-    get_diff_base_sha(repo_root)
+    # Fail fast if `asrt init` hasn't run — checkpoint/verify need the base
+    # SHA it records before doing any work or making any network calls.
+    read_init_base_sha(repo_root / ASSERTION_DIR_NAME)
     return repo_root
 
 
@@ -101,50 +121,6 @@ def _stacks_hint() -> str:
         )
 
 
-def resolve_stack_id_for_repo(repo_root: Path) -> str:
-    """Pick the stack whose `repo` field matches the current repo's origin.
-
-    Exits with a clear error if zero or more than one stack matches. The
-    enforcement is here (in the CLI) so the coding agent does not have to
-    follow a compliance rule — the rule is mechanical.
-    """
-    owner_name = get_origin_github_repo(repo_root)
-    if owner_name is None:
-        exit_with_error(
-            "Could not determine this repo's GitHub `owner/name` from the `origin` "
-            "remote. Pass `--stack <id>` explicitly to override."
-        )
-
-    client = AssertionClient()
-    stacks = client.stacks()
-
-    if not stacks:
-        exit_with_error(
-            "No verification stacks exist in this workspace yet. Open the "
-            "Assertion web app, create a stack, and attach this repo "
-            f"(`{owner_name}`) to it. Then re-run the command."
-        )
-
-    matches = [s for s in stacks if s.repo.strip() == owner_name]
-
-    if len(matches) == 1:
-        return matches[0].id
-    if len(matches) == 0:
-        bound_repos = sorted({s.repo.strip() for s in stacks})
-        exit_with_error(
-            f"No verification stack is attached to this repo (`{owner_name}`)."
-            f" Other stacks in this workspace are attached to: {', '.join(bound_repos)}."
-            " Open the Assertion web app, choose a stack,"
-            " and attach this repo to it. Then re-run the command."
-        )
-    # More than one match — let the agent / user pick explicitly.
-    names = ", ".join(f"{s.name} ({s.id})" for s in matches)
-    exit_with_error(
-        f"Multiple stacks are attached to `{owner_name}`: {names}. "
-        "Pass `--stack <id>` to disambiguate."
-    )
-
-
 def start_new_session(
     *,
     start_path: Path,
@@ -209,14 +185,20 @@ def append_checkpoint_entry(checkpoint_path: Path, message: str) -> None:
         f.write(f"{normalized}\n\n")
 
 
-def update_metadata_head(
+def update_metadata_anchor(
     metadata_path: Path,
     metadata: MetadataPayload,
-    head_sha: str,
+    base_sha: str,
     head_branch: str | None = None,
 ) -> MetadataPayload:
+    """Refresh the per-session git anchor: diff base + branch name.
+
+    `base_sha` is the diff base (recorded by `asrt init`, same value on every
+    call within a session). `head_branch` is the current local branch — may
+    legitimately change within a session if the user renames or switches.
+    """
     updated = metadata.model_copy(
-        update={"head_sha": head_sha, "head_branch": head_branch}
+        update={"base_sha": base_sha, "head_branch": head_branch}
     )
     metadata_path.write_text(updated.model_dump_json(indent=2) + "\n", encoding="utf-8")
     return updated

assertion_cli-0.2.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-api.py,sha256=6RuyOoZrsBTY_51XA60iHwkYJ6nqME0CrmDgGaEbWzk,6901
-bundle.py,sha256=e1-a0_hcKG0Xitjq0ac5u7ox3soAiodVbKIf4pRmI4w,828
-git.py,sha256=IDiy5ZQPJwCFEecTabmcaHA_jEyM06Al3hnY1lKqyRM,7637
-link.py,sha256=bfH0MhkeTFGbOSJbSvuuw3ilGX3akyvjvCw25AP_fz8,643
-main.py,sha256=7SwKc8n7YkD6Jh5dNgs1ul5BSlClp-5RaDv2FMPDBis,18121
-models.py,sha256=PQ0q_kUUzRVme325TXB_8eQaNl4LPSuxY8CVy9HK2ls,1678
-session.py,sha256=or0SQPuqJILe2wkQT32wmqY2TTXt0l5medIF7oZovNs,7130
-assertion_cli_templates/ACTIVATION.md,sha256=iDCSr87McqKX2ui1cQtKhk2Rcct04q_BIKAYpytaULo,1423
-assertion_cli_templates/SKILL.md,sha256=YTHMN8PQtkVzZEmPRMighHZ4zakwv1kOKqM0wT01hYY,13059
-assertion_cli_templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-assertion_cli-0.2.0.dist-info/METADATA,sha256=asC8-oqwe21zEdE8iPQSfB5kyXSFLIc3EuRzukdrkjY,1712
-assertion_cli-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-assertion_cli-0.2.0.dist-info/entry_points.txt,sha256=LgwuPLZEIk-4sD7ghGVRQOhm3PG8sPVozMRxrihwMgU,34
-assertion_cli-0.2.0.dist-info/top_level.txt,sha256=xbZYH9xQOa99z-Vbkc2Xp6h8oUR97DVlyczy8H4ZuFc,64
-assertion_cli-0.2.0.dist-info/RECORD,,