refactorai-cli 0.5.8__tar.gz → 0.6.0__tar.gz

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-cli
-Version: 0.5.8
+Version: 0.6.0
 Summary: Local-first CLI for the refactor platform
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "refactorai-cli"
-version = "0.5.8"
+version = "0.6.0"
 description = "Local-first CLI for the refactor platform"
 readme = "README.md"
 requires-python = ">=3.11"

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli/__init__.py

@@ -5,4 +5,4 @@ the shared `refactor_core` pipeline from a project folder while staying
 authenticated to the hosted platform via a developer key.
 """
 
-__version__ = "0.5.8"
+__version__ = "0.6.0"

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli/cloud_rr.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 from collections import deque
 import contextlib
 import hashlib
+import json
 import os
 import re
 import shlex
@@ -49,12 +50,13 @@ from refactor_core.refactor_requests import (
     DENIED,
     FAILED,
     IN_PROGRESS,
+    RefactorAttempt,
     pending_requests,
     rr_test_dir,
     save_request,
 )
 from refactor_core.host_toolchain import provision_for_command
-from refactor_core.store import create_run
+from refactor_core.store import create_run, resolve_store_dir
 from refactor_core.testcmd import (
     _SKIP_DIRS,
     _configured_command,
@@ -357,6 +359,94 @@ def _managed_toolchain_enabled(config: dict) -> bool:
     return True
 
 
+def _deps_restore_policy(config: dict) -> str:
+    """Return dependency-restore policy: ``auto`` (default), ``always``, ``never``."""
+    verification = (config or {}).get("verification")
+    raw = "auto"
+    if isinstance(verification, dict):
+        raw = str(verification.get("deps_restore_policy", "auto") or "auto")
+    policy = raw.strip().lower()
+    return policy if policy in {"auto", "always", "never"} else "auto"
+
+
+def _sha256_file(path: Path) -> str:
+    """Hash a file's bytes; ``""`` when unreadable/missing."""
+    if not path.is_file():
+        return ""
+    digest = hashlib.sha256()
+    try:
+        with path.open("rb") as fh:
+            for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+                digest.update(chunk)
+    except OSError:
+        return ""
+    return digest.hexdigest()
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    try:
+        obj = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return obj if isinstance(obj, dict) else {}
+
+
+def _write_json_atomic(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.tmp")
+    tmp.write_text(json.dumps(payload, sort_keys=True), encoding="utf-8")
+    tmp.replace(path)
+
+
+def _node_lockfile(project_root: Path) -> Path | None:
+    for name in ("package-lock.json", "npm-shrinkwrap.json"):
+        path = project_root / name
+        if path.is_file():
+            return path
+    return None
+
+
+def _node_deps_state_path(project_root: Path) -> Path:
+    return resolve_store_dir(project_root) / "toolchain-state" / "node-deps.json"
+
+
+def _node_deps_fingerprint(project_root: Path, env: dict, install_command: str) -> tuple[str, dict]:
+    lockfile = _node_lockfile(project_root)
+    node_bin = shutil.which("node", path=(env or {}).get("PATH"))
+    metadata = {
+        "install_command": install_command,
+        "package_json_sha256": _sha256_file(project_root / "package.json"),
+        "lockfile_name": lockfile.name if lockfile else "",
+        "lockfile_sha256": _sha256_file(lockfile) if lockfile else "",
+        # A different binary path often means a different runtime version/build.
+        "node_binary_path": str(Path(node_bin).resolve()) if node_bin else "",
+    }
+    digest = hashlib.sha256(
+        json.dumps(metadata, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+    return digest, metadata
+
+
+def _should_restore_node_dependencies(
+    project_root: Path, env: dict, install_command: str
+) -> tuple[bool, str, dict]:
+    """Return ``(should_restore, reason, marker_payload)`` for node deps."""
+    fingerprint, metadata = _node_deps_fingerprint(project_root, env, install_command)
+    payload = {"fingerprint": fingerprint, "metadata": metadata}
+    if not (project_root / "node_modules").is_dir():
+        return True, "node_modules missing", payload
+    state = _read_json(_node_deps_state_path(project_root))
+    if not state:
+        return True, "cache marker missing", payload
+    if str(state.get("fingerprint") or "") != fingerprint:
+        return True, "dependency fingerprint changed", payload
+    return False, "dependency fingerprint unchanged", payload
+
+
 def _detected_is_provisionable(command: str | None) -> bool:
     """True when every missing binary of ``command`` maps to a managed runtime.
 
@@ -456,40 +546,72 @@ def _provision_toolchain(
             continue
         _emit(progress_cb, phase="rr", event="toolchain_ready", runtime=runtime)
         merged_env = _merge_toolchain_env(merged_env, env)
-        _restore_dependencies(project_root, runtime, merged_env, progress_cb)
+        _restore_dependencies(project_root, runtime, merged_env, progress_cb, config=config)
 
     return merged_env, " ".join(n for n in notes if n).strip()
 
 
 def _restore_dependencies(
-    project_root: Path, runtime: str, env: dict, progress_cb: Callable[[dict], None] | None
+    project_root: Path,
+    runtime: str,
+    env: dict,
+    progress_cb: Callable[[dict], None] | None,
+    *,
+    config: dict,
 ) -> None:
     """Restore project dependencies with the provisioned toolchain (best effort).
 
     Mirrors the sandbox dependency-restore step so the test command has its deps
     present. Failures are non-fatal: the test run surfaces the real error.
     """
+    policy = _deps_restore_policy(config)
+    if policy == "never":
+        _emit(
+            progress_cb,
+            phase="rr",
+            event="toolchain_provisioning",
+            detail=f"dependency restore skipped for {runtime} (policy=never)",
+        )
+        return
     if runtime == "node" and (project_root / "package.json").is_file():
+        lockfile = _node_lockfile(project_root)
+        install_command = "npm ci" if lockfile is not None else "npm install"
+        marker_payload: dict | None = None
+        if policy == "auto":
+            should_restore, reason, marker_payload = _should_restore_node_dependencies(
+                project_root, env, install_command
+            )
+            if not should_restore:
+                _emit(
+                    progress_cb,
+                    phase="rr",
+                    event="toolchain_provisioning",
+                    detail=f"skipping node dependency restore ({reason})",
+                )
+                return
         _emit(
             progress_cb,
             phase="rr",
             event="toolchain_provisioning",
-            detail="step 1/1: npm install (streaming output below)",
+            detail=f"step 1/1: {install_command} (streaming output below)",
         )
         ok, detail = _run_command_with_progress(
             project_root,
-            "npm install",
+            install_command,
             env=env,
             progress_cb=progress_cb,
             label="npm",
             timeout=1800,
         )
+        if ok and policy == "auto" and marker_payload is not None:
+            with contextlib.suppress(OSError):
+                _write_json_atomic(_node_deps_state_path(project_root), marker_payload)
         if not ok:
             _emit(
                 progress_cb,
                 phase="rr",
                 event="toolchain_provisioning",
-                detail=f"npm install finished with errors: {detail}",
+                detail=f"{install_command} finished with errors: {detail}",
             )
     elif runtime == "python":
         if (project_root / "requirements.txt").is_file():
@@ -1025,8 +1147,16 @@ def run_cloud_refactor_requests(
             diff_text = str(action.get("diff_text", "") or "")
             attempt = int(action.get("attempt", 1) or 1)
             attempts_by_id[current_rr_id] = attempt
+            _PENDING_ATTEMPT[current_rr_id] = RefactorAttempt(
+                proposal_n=attempt,
+                diff_text=diff_text,
+            )
             ok, why = validate_diff(project_root, diff_text)
             if not ok:
+                pending = _PENDING_ATTEMPT.pop(current_rr_id, None)
+                if pending is not None:
+                    pending.detail = f"invalid diff: {why}"
+                _persist_attempt(project_root, rr, pending, attempt)
                 _emit(progress_cb, phase="rr", event="proposal_invalid", attempt=attempt, reason=why)
                 action = session.step(
                     _step_payload(token, current_rr_id, "verify_result", by_id, project_root,
@@ -1044,6 +1174,14 @@ def run_cloud_refactor_requests(
                 "risk": action.get("risk", "medium"),
                 "diff_text": diff_text,
             }))
+            pending = _PENDING_ATTEMPT.get(current_rr_id)
+            if pending is not None:
+                pending.approved = approved
+            if not approved:
+                pending = _PENDING_ATTEMPT.pop(current_rr_id, None)
+                if pending is not None:
+                    pending.detail = "denied by developer"
+                _persist_attempt(project_root, rr, pending, attempt)
             _emit(progress_cb, phase="rr", event="approval_decision", rr_id=current_rr_id, approved=approved)
             _PENDING_DIFF[current_rr_id] = diff_text
             action = session.step(
@@ -1058,18 +1196,32 @@ def run_cloud_refactor_requests(
             if verdict == "":
                 # Server approved: client applies + verifies, then posts result.
                 current_rr_id = action.get("rr_id", "") or current_rr_id
+                rr = by_id.get(current_rr_id)
                 diff_text = _PENDING_DIFF.get(current_rr_id, "")
+                attempt_n = attempts_by_id.get(current_rr_id, 1)
+                pending = _PENDING_ATTEMPT.pop(current_rr_id, None)
+                if pending is None:
+                    pending = RefactorAttempt(
+                        proposal_n=attempt_n,
+                        diff_text=diff_text,
+                        approved=True,
+                    )
                 passed, detail, files = _apply_and_verify(
                     project_root, run_store.run_dir, diff_text, test_command, env=toolchain_env
                 )
+                pending.applied = True
                 if passed:
+                    pending.test_passed = True
                     _emit(progress_cb, phase="rr", event="rr_applied", rr_id=current_rr_id, files=files)
                 else:
+                    pending.reverted = True
+                    pending.detail = f"verification failed: {detail}"
                     _emit(progress_cb, phase="rr", event="rr_reverted", rr_id=current_rr_id,
-                          attempt=attempts_by_id.get(current_rr_id, 1), detail=detail)
+                          attempt=attempt_n, detail=detail)
+                _persist_attempt(project_root, rr, pending, attempt_n)
                 action = session.step(
                     _step_payload(token, current_rr_id, "verify_result", by_id, project_root,
-                                  attempt=attempts_by_id.get(current_rr_id, 1),
+                                  attempt=attempt_n,
                                   verify_passed=passed, verify_detail=detail)
                 )
                 token = action.get("session_token", token)
@@ -1110,6 +1262,20 @@ def run_cloud_refactor_requests(
 
 # Diffs approved but not yet applied, keyed by rr_id (client-local, per run).
 _PENDING_DIFF: dict[str, str] = {}
+# Attempt snapshots keyed by rr_id; persisted when each proposal reaches a
+# terminal sub-outcome so telemetry can carry attempts[].diff_text.
+_PENDING_ATTEMPT: dict[str, RefactorAttempt] = {}
+
+
+def _persist_attempt(project_root: Path, rr, attempt: RefactorAttempt | None, attempt_n: int) -> None:
+    if rr is None or attempt is None:
+        return
+    rr.attempts.append(attempt)
+    rr.attempt_count = max(
+        int(getattr(rr, "attempt_count", 0) or 0),
+        int(attempt_n or getattr(attempt, "proposal_n", 0) or 0),
+    )
+    save_request(project_root, rr)
 
 
 def _step_payload(token, rr_id, step, by_id, project_root, *, attempt: int = 0, **kw) -> dict:

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli/commands/run_cmds.py

@@ -2273,6 +2273,9 @@ def _refactor_branch_name(
     template: str = "refactor/{branch}/{shortsha}",
 ) -> str:
     """Compose ``refactor/<sanitized-branch>/<shortsha>`` (detached-safe)."""
+    from refactorai_cli.refactor_branch_store import debase_source_branch
+
+    source_branch = debase_source_branch(source_branch)
     if source_branch and source_branch != "HEAD":
         branch = _sanitize_branch_component(source_branch)
     else:
@@ -2671,7 +2674,11 @@ def _prepare_refactor_branch(
     if not source_sha:
         console.print(f"[yellow]code: could not resolve commit '{commit}' for branch; applying in place.[/yellow]")
         return None
-    source_branch = git_scope.current_branch(project_root)
+    # Anchor to the developer's primary branch, never the current HEAD: when a
+    # terminal action runs while HEAD is already on a refactor sub-branch, using
+    # the current branch would nest the name (``refactor/refactor/...``). The
+    # primary branch keeps every sub-branch flat and its source association true.
+    source_branch = git_scope.resolve_primary_branch(project_root)
     branch_name = _refactor_branch_name(source_branch, source_sha, template=template)
 
     # The reviewed commit names the branch + anchors metadata; the checkout base

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli/commands/toolchains_cmds.py

@@ -16,6 +16,7 @@ from refactor_core import host_toolchain as ht
 
 console = Console()
 app = typer.Typer(help="Inspect and manage managed language toolchains.")
+_SUPPORTED_RUNTIMES = ("node", "python", "go")
 
 
 @app.command("list")
@@ -55,3 +56,44 @@ def prune_toolchains(
         return
     for path in removed:
         console.print(f"[green]removed[/green] {path}")
+
+
+@app.command("prewarm")
+def prewarm_toolchains(
+    runtime: list[str] = typer.Option(
+        [],
+        "--runtime",
+        "-r",
+        help="Runtime to prewarm (repeatable): node, python, go. Defaults to all.",
+    ),
+) -> None:
+    """Download pinned runtimes into the local toolchain cache."""
+    requested = [str(r or "").strip().lower() for r in runtime]
+    if not requested:
+        targets = list(_SUPPORTED_RUNTIMES)
+    else:
+        bad = sorted({r for r in requested if r not in _SUPPORTED_RUNTIMES})
+        if bad:
+            supported = ", ".join(_SUPPORTED_RUNTIMES)
+            console.print(
+                f"[red]Unsupported runtime(s):[/red] {', '.join(bad)}. "
+                f"Supported: {supported}."
+            )
+            raise typer.Exit(code=1)
+        targets = list(dict.fromkeys(requested))
+
+    failures: list[str] = []
+    for idx, name in enumerate(targets, start=1):
+        console.print(f"[cyan]prewarm {idx}/{len(targets)}[/cyan]: {name}")
+        try:
+            ht.ensure_runtime(name, on_progress=lambda msg: console.print(f"[dim]  {msg}[/dim]"))
+        except Exception as exc:
+            failures.append(f"{name}: {exc}")
+            continue
+        console.print(f"[green]ready[/green] {name}")
+
+    if failures:
+        console.print("[red]Prewarm finished with failures:[/red]")
+        for item in failures:
+            console.print(f"[red]  - {item}[/red]")
+        raise typer.Exit(code=1)

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli/commands/watch_cmds.py

@@ -30,6 +30,7 @@ from refactorai_cli import (
     commit_queue,
     git_scope,
     refactor_branch_store,
+    watch_ledger,
     watch_state,
     watch_supervisor,
 )
@@ -39,6 +40,7 @@ from refactorai_cli.watch_state import (
     FinalizeInfo,
     RRCommit,
     WatchState,
+    hydrate_node_from_ledger,
     render_graph,
 )
 
@@ -268,6 +270,61 @@ def refresh_finalize(project_root: Path, state: WatchState) -> None:
             node.finalize = resolve_finalize(project_root, node)
 
 
+def _ingest_event(project_root: Path, state: WatchState, event: dict) -> None:
+    """Add a queued node for ``event``, rehydrating it from the ledger if known.
+
+    Runs only for brand-new shas (``state.has`` guards re-entry), so a
+    deliberately requeued node — e.g. after ``[f]`` fresh review — is never
+    silently restored to its old reviewed state. A commit the ledger already has
+    is rehydrated (rendered as history) instead of being re-analyzed; its open
+    request count is re-derived live from the RR store so the phase stays honest
+    even though prior requests may since have been resolved (Phase 2).
+    """
+    sha = str(event.get("sha") or "")
+    if not sha or state.has(sha):
+        return
+    node = state.upsert_from_event(event)
+    record = watch_ledger.get_commit(project_root, sha)
+    if not record:
+        return
+    hydrate_node_from_ledger(node, record)
+    if node.run_id:
+        pending_count, preview = _pending_for_run(project_root, node.run_id)
+        node.rr_count = pending_count
+        node.rr_preview = preview
+
+
+def reconcile_merged(project_root: Path, state: WatchState, *, deep: bool = False) -> None:
+    """Detect refactor branches integrated into the primary branch out-of-band.
+
+    The ``[m]`` merge path already records a ``merged`` outcome; this catches the
+    case where the developer merged (or squash/rebase-merged with ``deep``) the
+    refactor branch via plain git. When detected, the branch's outcome is
+    tombstoned so the node collapses to a DONE row and the commit becomes
+    terminal in the ledger — never re-queued or re-analyzed again.
+    """
+    primary = getattr(state, "primary_branch", "") or ""
+    if not primary:
+        return
+    for node in state.nodes_oldest_first():
+        fin = getattr(node, "finalize", None)
+        if fin is None or not fin.branch_exists:
+            continue
+        if fin.outcome in (refactor_branch_store.OUTCOME_MERGED, refactor_branch_store.OUTCOME_DROPPED):
+            continue
+        try:
+            merged = git_scope.branch_merged_into(project_root, fin.refactor_branch, primary, deep=deep)
+        except Exception:
+            merged = False
+        if not merged:
+            continue
+        refactor_branch_store.set_outcome(
+            project_root, fin.refactor_branch, refactor_branch_store.OUTCOME_MERGED
+        )
+        node.finalize = resolve_finalize(project_root, node)
+        watch_ledger.record_commit(project_root, node)
+
+
 def _resolve_repo(project_root: Path | None) -> Path:
     root = git_scope.repo_root(project_root or Path.cwd())
     if not root:
@@ -302,15 +359,31 @@ def _ensure_auth_in_window(json_mode: bool) -> None:
             raise typer.Exit(code=1) from exc2
 
 
-def _load_initial_events(project_root: Path, since: str | None, limit: int) -> list[dict]:
-    """Queue events to render on start, optionally sliced by ``--since`` / ``--limit``."""
+def _load_initial_events(
+    project_root: Path,
+    since: str | None,
+    limit: int,
+    *,
+    watermark: str | None = None,
+) -> list[dict]:
+    """Queue events to render on start, sliced by ``--since`` / watermark / ``--limit``.
+
+    An explicit ``--since`` wins. Otherwise the persisted review watermark (the
+    newest commit already reviewed on the primary branch) bounds the scan so each
+    launch is O(new commits) rather than re-loading the whole append-only queue
+    (Phase 2). ``--limit`` still caps the render for a very large first run.
+    """
     events = commit_queue.read_events(project_root)
-    if since:
-        since_sha = git_scope.resolve_sha(project_root, since)
-        if since_sha:
+    anchor = since or watermark
+    anchor_is_watermark = not since and bool(watermark)
+    if anchor:
+        anchor_sha = git_scope.resolve_sha(project_root, anchor)
+        if anchor_sha:
             for idx, ev in enumerate(events):
-                if ev.get("sha") == since_sha:
-                    events = events[idx:]
+                if ev.get("sha") == anchor_sha:
+                    # The watermark commit is already reviewed -> start *after* it;
+                    # an explicit --since is inclusive of the named commit.
+                    events = events[idx + 1:] if anchor_is_watermark else events[idx:]
                     break
     if limit and limit > 0:
         events = events[-limit:]
@@ -366,16 +439,20 @@ def process_pending(
     except Exception:
         pass
     for event in commit_queue.read_events(project_root):
-        sha = str(event.get("sha") or "")
-        if sha and not state.has(sha):
-            state.upsert_from_event(event)
+        _ingest_event(project_root, state, event)
     if on_update:
         on_update(state)
 
     reviewed = 0
+    newest_reviewed = ""
     for node in state.nodes_oldest_first():
         if node.state != watch_state.QUEUED:
             continue
+        # A commit finalized in a previous session (merged/dropped) is terminal:
+        # never re-analyze it, even if it is still sitting in the append-only
+        # queue (Phase 2 core fix).
+        if watch_ledger.is_terminal(watch_ledger.get_status(project_root, node.sha)):
+            continue
         state.mark_reviewing(node.sha)
         if on_update:
             on_update(state)
@@ -390,12 +467,21 @@ def process_pending(
             outcome.rr_preview = _preview_for_run(project_root, outcome.run_id)
         state.apply_outcome(node.sha, outcome)
         reviewed += 1
+        newest_reviewed = node.sha
         if on_update:
             on_update(state)
         _report_node(project_root, node)
+        # Persist the outcome so a relaunched terminal renders it as history
+        # instead of re-running the model on this commit.
+        watch_ledger.record_commit(project_root, state.get(node.sha))
     # docs/43 Phase 1: fold current refactor-branch data into reviewed nodes so
     # their phase (review/finalize/done) reflects any branch built by `[r]`.
     refresh_finalize(project_root, state)
+    # Detect out-of-band merges (deep scan only when we actually did work this
+    # pass, so idle polls stay cheap) and advance the review watermark.
+    reconcile_merged(project_root, state, deep=bool(reviewed))
+    if reviewed and newest_reviewed:
+        watch_ledger.set_watermark(project_root, state.primary_branch or state.current_branch, newest_reviewed)
     if on_update:
         on_update(state)
     if reviewed:
@@ -544,6 +630,28 @@ def _sync_current_branch(project_root: Path, state: WatchState) -> None:
         pass
 
 
+def _return_to_primary(project_root: Path, state: WatchState) -> None:
+    """Restore HEAD to the developer's primary branch after a terminal action.
+
+    Resolving (``[r]``) leaves HEAD on the refactor sub-branch; if the next commit
+    is authored there the sub-branch name nests (``refactor/refactor/...``).
+    Checking back out onto the primary branch keeps every future commit — and
+    thus every future sub-branch — anchored to the user's real branch. Fail-soft:
+    a dirty tree or missing branch simply leaves HEAD where it is (Phase 1, A4).
+    """
+    primary = getattr(state, "primary_branch", "") or ""
+    if not primary or primary == "HEAD":
+        _sync_current_branch(project_root, state)
+        return
+    try:
+        current = git_scope.current_branch(project_root)
+        if current != primary and git_scope.branch_exists(project_root, primary):
+            git_scope.checkout(project_root, primary)
+    except Exception:
+        pass
+    _sync_current_branch(project_root, state)
+
+
 def _run_action(
     live,
     project_root: Path,
@@ -582,16 +690,31 @@ def _run_action(
             pending_count, preview = _pending_for_run(project_root, node_after.run_id)
             node_after.rr_count = pending_count
             node_after.rr_preview = preview
-        _sync_current_branch(project_root, state)
+        # `[r]` leaves HEAD on the sub-branch; return to primary so the next
+        # commit (and its sub-branch) never nests (Phase 1, A4).
+        _return_to_primary(project_root, state)
         refresh_finalize(project_root, state)
+        refreshed = state.get(node.sha)
+        if refreshed is not None:
+            watch_ledger.record_commit(project_root, refreshed)
     elif action in ("merge", "drop", "revert"):
         # Finalize actions (docs/43). `merge_branch` records the merged outcome
         # itself; a completed drop leaves no branch, so tombstone the dropped
         # outcome here so the node collapses to a DONE (dropped) row.
         if action == "drop" and branch and not git_scope.branch_exists(project_root, branch):
             refactor_branch_store.set_outcome(project_root, branch, refactor_branch_store.OUTCOME_DROPPED)
-        _sync_current_branch(project_root, state)
+        # After merge/drop end on the primary branch; revert stays in place.
+        if action in ("merge", "drop"):
+            _return_to_primary(project_root, state)
+        else:
+            _sync_current_branch(project_root, state)
         refresh_finalize(project_root, state)
+        # Persist the terminal outcome so the ledger short-circuits this commit
+        # on the next launch (no re-review, no re-queued requests).
+        if action in ("merge", "drop"):
+            refreshed = state.get(node.sha)
+            if refreshed is not None:
+                watch_ledger.record_commit(project_root, refreshed)
     # `[r]`/`[m]`/`[d]` can change RR status; mirror the local store to the Inbox.
     if action in ("code", "merge", "drop"):
         _report_refactor_requests(project_root)
@@ -862,12 +985,13 @@ def watch(
     state = WatchState(repo_name=project_root.name)
     try:
         state.current_branch = git_scope.current_branch(project_root) or ""
+        state.primary_branch = git_scope.resolve_primary_branch(project_root) or ""
     except Exception:
         state.current_branch = ""
-    for event in _load_initial_events(project_root, since, limit):
-        sha = str(event.get("sha") or "")
-        if sha and not state.has(sha):
-            state.upsert_from_event(event)
+    watch_ledger.set_primary_branch(project_root, state.primary_branch)
+    watermark = watch_ledger.get_watermark(project_root, state.primary_branch or state.current_branch)
+    for event in _load_initial_events(project_root, since, limit, watermark=watermark):
+        _ingest_event(project_root, state, event)
 
     runner: ReviewRunner = SubprocessReviewRunner(project_root)
 
@@ -970,12 +1094,13 @@ def ensure(
         state = WatchState(repo_name=project_root.name)
         try:
             state.current_branch = git_scope.current_branch(project_root) or ""
+            state.primary_branch = git_scope.resolve_primary_branch(project_root) or ""
         except Exception:
             state.current_branch = ""
-        for event in _load_initial_events(project_root, None, 20):
-            sha = str(event.get("sha") or "")
-            if sha and not state.has(sha):
-                state.upsert_from_event(event)
+        watch_ledger.set_primary_branch(project_root, state.primary_branch)
+        watermark = watch_ledger.get_watermark(project_root, state.primary_branch or state.current_branch)
+        for event in _load_initial_events(project_root, None, 20, watermark=watermark):
+            _ingest_event(project_root, state, event)
         runner: ReviewRunner = SubprocessReviewRunner(project_root)
         _open_watch_window(project_root, state, runner)
         return

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli/commit_queue.py

@@ -65,7 +65,10 @@ def build_commit_event(project_root: Path | str, sha: str) -> dict | None:
     subject, message = git_scope.commit_message(project_root, resolved)
     return {
         "sha": resolved,
-        "branch": git_scope.current_branch(project_root),
+        # Record the developer's primary branch, not a refactor sub-branch: a
+        # stray commit authored on a ``refactor/*`` ref would otherwise seed the
+        # nested-name problem for the next sub-branch (Phase 1, A5).
+        "branch": git_scope.resolve_primary_branch(project_root),
         "subject": subject,
         "message": message,
         "changed_files": git_scope.commit_changed_files(project_root, resolved),

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli/git_scope.py

@@ -140,6 +140,79 @@ def current_branch(project_root: Path | str) -> str:
     return proc.stdout.strip()
 
 
+def is_refactor_ref(name: str) -> bool:
+    """True when ``name`` is a refactor sub-branch (``refactor/...``).
+
+    The refactor flow must never treat one of its own sub-branches as the
+    developer's base, otherwise sub-branch names nest (``refactor/refactor/...``).
+    """
+    return str(name or "").strip().startswith("refactor/")
+
+
+def default_branch(project_root: Path | str) -> str:
+    """Best-effort default branch (``origin/HEAD`` -> ``main`` -> ``master``).
+
+    Used as the last-resort primary branch when HEAD is detached or the current
+    ref is a refactor sub-branch with no recorded source. Returns ``""`` when
+    nothing sensible can be resolved.
+    """
+    proc = _git(project_root, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+    if proc and proc.returncode == 0:
+        ref = proc.stdout.strip()
+        if ref:
+            name = ref.rsplit("/", 1)[-1].strip()
+            if name and not is_refactor_ref(name):
+                return name
+    for candidate in ("main", "master"):
+        if branch_exists(project_root, candidate):
+            return candidate
+    return ""
+
+
+def resolve_primary_branch(project_root: Path | str) -> str:
+    """Resolve the developer's primary (working) branch, never a ``refactor/*``.
+
+    This is the single source of truth for "which branch does the user own": the
+    refactor sub-branch flow anchors its base and naming to this so a sub-branch
+    is always ``refactor/<primary>/<sha>`` (flat), even when the terminal action
+    is invoked while HEAD is standing on a previously-created sub-branch.
+
+    Resolution order (docs Phase 1, A1):
+      1. the current branch, if it is not itself a refactor ref;
+      2. otherwise walk the recorded ``source_branch`` of the current refactor
+         sub-branch until a non-refactor base is found;
+      3. otherwise fall back to the repo default branch.
+    """
+    current = current_branch(project_root)
+    if current and current != "HEAD" and not is_refactor_ref(current):
+        return current
+
+    # HEAD is detached or sitting on a refactor sub-branch: walk the source chain.
+    try:
+        from refactorai_cli import refactor_branch_store
+    except Exception:
+        refactor_branch_store = None
+
+    branch = current
+    seen: set[str] = set()
+    while (
+        refactor_branch_store is not None
+        and branch
+        and is_refactor_ref(branch)
+        and branch not in seen
+    ):
+        seen.add(branch)
+        meta = refactor_branch_store.load_branch(project_root, branch)
+        source = str(getattr(meta, "source_branch", "") or "") if meta else ""
+        if not source:
+            break
+        branch = source
+
+    if branch and branch != "HEAD" and not is_refactor_ref(branch):
+        return branch
+    return default_branch(project_root)
+
+
 def commit_parent_count(project_root: Path | str, sha: str) -> int:
     """Number of parents of ``sha`` (a merge commit has >= 2)."""
     sha = (sha or "").strip()
@@ -405,6 +478,95 @@ def commit_sha_for_rr(project_root: Path | str, rr_id: str) -> str | None:
     return sha[0].strip() if sha and sha[0].strip() else None
 
 
+def is_ancestor(project_root: Path | str, maybe_ancestor: str, descendant: str) -> bool:
+    """True when ``maybe_ancestor`` is reachable from ``descendant`` (merged in).
+
+    Uses ``git merge-base --is-ancestor`` (exit 0 == ancestor, 1 == not). Any
+    other outcome (bad ref, git error) fails soft to ``False``.
+    """
+    a = (maybe_ancestor or "").strip()
+    b = (descendant or "").strip()
+    if not a or not b:
+        return False
+    proc = _git(project_root, "merge-base", "--is-ancestor", a, b)
+    return bool(proc) and proc.returncode == 0
+
+
+def rev_list(project_root: Path | str, ref: str, *, limit: int = 50) -> list[str]:
+    """Up to ``limit`` commit SHAs reachable from ``ref`` (newest first)."""
+    ref = (ref or "").strip()
+    if not ref:
+        return []
+    args = ["rev-list", ref]
+    if limit and limit > 0:
+        args.append(f"--max-count={int(limit)}")
+    proc = _git(project_root, *args)
+    if not proc or proc.returncode != 0:
+        return []
+    return [line.strip() for line in proc.stdout.splitlines() if line.strip()]
+
+
+def patch_id(project_root: Path | str, ref: str) -> str:
+    """Stable patch-id of a commit's diff, or ``""`` on failure.
+
+    Survives rebase/cherry-pick/squash (content-addressed rather than SHA-based),
+    so it can detect that a refactor branch was integrated even when the merge
+    rewrote history. Pipes ``git show`` into ``git patch-id --stable``.
+    """
+    ref = (ref or "").strip()
+    if not ref:
+        return ""
+    try:
+        show = subprocess.run(
+            ["git", "-C", str(project_root), "show", "--format=%H", ref],
+            capture_output=True,
+            text=True,
+            timeout=_TIMEOUT,
+            check=False,
+        )
+        if show.returncode != 0 or not show.stdout:
+            return ""
+        pid = subprocess.run(
+            ["git", "-C", str(project_root), "patch-id", "--stable"],
+            input=show.stdout,
+            capture_output=True,
+            text=True,
+            timeout=_TIMEOUT,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    if pid.returncode != 0 or not pid.stdout.strip():
+        return ""
+    # Output is "<patch-id> <commit-sha>"; keep the patch-id half.
+    return pid.stdout.strip().split()[0]
+
+
+def branch_merged_into(
+    project_root: Path | str, branch: str, target: str, *, deep: bool = False, window: int = 50
+) -> bool:
+    """True when ``branch`` has been integrated into ``target``.
+
+    Cheap path (always): ``branch`` tip is an ancestor of ``target`` (covers
+    fast-forward and ``--no-ff`` merges, including a manual ``git merge`` done
+    outside the terminal). ``deep`` additionally compares the branch tip's
+    patch-id against ``target``'s recent history to catch squash/rebase merges;
+    it is opt-in because it runs one ``patch-id`` per scanned commit.
+    """
+    branch = (branch or "").strip()
+    target = (target or "").strip()
+    if not branch or not target:
+        return False
+    if is_ancestor(project_root, branch, target):
+        return True
+    if not deep:
+        return False
+    bpid = patch_id(project_root, branch)
+    if not bpid:
+        return False
+    return any(patch_id(project_root, sha) == bpid for sha in rev_list(project_root, target, limit=window))
+
+
 def commit_message(project_root: Path | str, sha: str) -> tuple[str, str]:
     """Return ``(subject, full_message)`` for commit ``sha`` (empty on failure)."""
     sha = (sha or "").strip()

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli/refactor_branch_store.py

@@ -48,6 +48,22 @@ def sanitize_branch_component(value: str) -> str:
     return (cleaned or "work")[:60]
 
 
+def debase_source_branch(source_branch: str) -> str:
+    """Strip any leading ``refactor/<base>/...`` so a name can never nest.
+
+    A refactor sub-branch is always ``refactor/<component>/<shortsha>`` (the
+    ``<component>`` never contains a slash — ``sanitize_branch_component`` folds
+    them to ``-``). If a caller mistakenly passes a refactor ref as the source
+    branch we peel it back to its ``<component>`` so the composed name stays flat
+    (``refactor/refactor/...`` can never be produced). Phase 1 backstop.
+    """
+    b = str(source_branch or "").strip()
+    while b.startswith("refactor/"):
+        parts = b.split("/")
+        b = parts[1] if len(parts) > 1 else ""
+    return b
+
+
 def refactor_branch_name(
     source_branch: str,
     source_sha: str,
@@ -55,6 +71,7 @@ def refactor_branch_name(
     template: str = "refactor/{branch}/{shortsha}",
 ) -> str:
     """Compose ``refactor/<sanitized-branch>/<shortsha>`` (detached-safe)."""
+    source_branch = debase_source_branch(source_branch)
     if source_branch and source_branch != "HEAD":
         branch = sanitize_branch_component(source_branch)
     else:

refactorai_cli-0.6.0/refactorai_cli/watch_ledger.py

@@ -0,0 +1,199 @@
+"""Durable per-repo review ledger for the Refactor Terminal (Phase 2).
+
+The in-memory ``WatchState`` is rebuilt from scratch every time ``refactor watch``
+launches, and the commit queue is append-only, so without a durable record the
+terminal re-runs the model on every commit it already analyzed (and re-surfaces
+requests that were already resolved/merged). This module persists, per repo, the
+outcome of each commit review plus a per-branch watermark so a relaunched window
+*renders history* instead of re-reviewing.
+
+Storage lives beside the commit queue (``<git-dir>/refactor-runs/
+review_ledger.json``) so it is per-repo, never tracked, and excluded from
+indexing. Everything is best-effort and fail-soft: a missing/corrupt ledger
+reads as empty and a failed write is swallowed, so the terminal never crashes or
+stalls because of ledger I/O.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from refactorai_cli import commit_queue
+
+LEDGER_FILENAME = "review_ledger.json"
+LEDGER_VERSION = 1
+
+# Persisted per-commit review statuses (a superset view of the in-memory
+# lifecycle in ``watch_state``): a commit is analyzed once and then tracked as it
+# moves toward a terminal ``merged``/``dropped`` outcome.
+QUEUED = "queued"
+REVIEWING = "reviewing"
+REVIEWED = "reviewed"
+FINALIZING = "finalizing"
+MERGED = "merged"
+DROPPED = "dropped"
+ERROR = "error"
+
+# Terminal states are never re-queued or re-analyzed.
+_TERMINAL = {MERGED, DROPPED}
+# States that mean "already analyzed" -> the node rehydrates as REVIEWED.
+_REVIEWED_LIKE = {REVIEWED, FINALIZING, MERGED, DROPPED}
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _empty() -> dict:
+    return {"version": LEDGER_VERSION, "primary_branch": "", "watermark": {}, "commits": {}}
+
+
+def ledger_path(project_root: Path | str) -> Path | None:
+    """Path to the per-repo review ledger, or ``None`` outside a git dir."""
+    directory = commit_queue.runs_dir(project_root)
+    return directory / LEDGER_FILENAME if directory else None
+
+
+def load_ledger(project_root: Path | str) -> dict:
+    """Read the ledger (normalized shape); an empty ledger on any failure."""
+    path = ledger_path(project_root)
+    if not path or not path.is_file():
+        return _empty()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return _empty()
+    if not isinstance(data, dict):
+        return _empty()
+    data.setdefault("version", LEDGER_VERSION)
+    data.setdefault("primary_branch", "")
+    if not isinstance(data.get("commits"), dict):
+        data["commits"] = {}
+    if not isinstance(data.get("watermark"), dict):
+        data["watermark"] = {}
+    return data
+
+
+def _write(project_root: Path | str, data: dict) -> None:
+    path = ledger_path(project_root)
+    if not path:
+        return
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        data["updated_at"] = _now_iso()
+        path.write_text(json.dumps(data, indent=2, sort_keys=True), encoding="utf-8")
+    except OSError:
+        pass
+
+
+def is_terminal(status: str) -> bool:
+    """True when a commit's review is finalized (``merged``/``dropped``)."""
+    return str(status or "") in _TERMINAL
+
+
+def is_reviewed_like(status: str) -> bool:
+    """True when the status means the commit was already analyzed."""
+    return str(status or "") in _REVIEWED_LIKE
+
+
+def get_commit(project_root: Path | str, sha: str) -> dict | None:
+    """The stored record for ``sha``, or ``None`` if never reviewed."""
+    sha = str(sha or "")
+    if not sha:
+        return None
+    return load_ledger(project_root)["commits"].get(sha) or None
+
+
+def get_status(project_root: Path | str, sha: str) -> str:
+    """The stored review status for ``sha`` (``""`` when unknown)."""
+    rec = get_commit(project_root, sha)
+    return str(rec.get("status", "")) if rec else ""
+
+
+def _status_for_node(node) -> str:
+    """Derive the persisted status from a live ``CommitNode``."""
+    fin = getattr(node, "finalize", None)
+    outcome = str(getattr(fin, "outcome", "") or "") if fin else ""
+    if outcome in _TERMINAL:
+        return outcome
+    state = str(getattr(node, "state", "") or "")
+    if state == "error":
+        return ERROR
+    if state == "reviewing":
+        return REVIEWING
+    if state == "reviewed":
+        # A resolved commit sitting on a live refactor branch is mid-finalize.
+        if fin is not None and getattr(fin, "branch_exists", False) and int(getattr(node, "rr_count", 0) or 0) == 0:
+            return FINALIZING
+        return REVIEWED
+    return QUEUED
+
+
+def record_commit(project_root: Path | str, node) -> None:
+    """Persist (or refresh) the review record for a commit node."""
+    if node is None:
+        return
+    sha = str(getattr(node, "sha", "") or "")
+    if not sha:
+        return
+    data = load_ledger(project_root)
+    existing = data["commits"].get(sha, {})
+    fin = getattr(node, "finalize", None)
+    status = _status_for_node(node)
+    reviewed_at = existing.get("reviewed_at") or ""
+    if not reviewed_at and is_reviewed_like(status):
+        reviewed_at = _now_iso()
+    data["commits"][sha] = {
+        "sha": sha,
+        "branch": str(getattr(node, "branch", "") or ""),
+        "subject": str(getattr(node, "subject", "") or ""),
+        "status": status,
+        "run_id": str(getattr(node, "run_id", "") or ""),
+        "gate_status": str(getattr(node, "gate_status", "") or ""),
+        "high_findings": int(getattr(node, "high_findings", 0) or 0),
+        "rr_count": int(getattr(node, "rr_count", 0) or 0),
+        "scope_mode": str(getattr(node, "scope_mode", "commit") or "commit"),
+        "changed": int(getattr(node, "changed", 0) or 0),
+        "associated": int(getattr(node, "associated", 0) or 0),
+        "intent_summary": str(getattr(node, "intent_summary", "") or ""),
+        "refactor_branch": str(getattr(fin, "refactor_branch", "") or "") if fin else "",
+        "outcome": str(getattr(fin, "outcome", "") or "") if fin else "",
+        "reviewed_at": reviewed_at,
+        "updated_at": _now_iso(),
+    }
+    _write(project_root, data)
+
+
+def mark_merged(project_root: Path | str, sha: str) -> None:
+    """Force a commit's record to the terminal ``merged`` state (reconciler)."""
+    sha = str(sha or "")
+    if not sha:
+        return
+    data = load_ledger(project_root)
+    rec = data["commits"].get(sha)
+    if not rec:
+        return
+    rec["status"] = MERGED
+    rec["outcome"] = MERGED
+    rec["updated_at"] = _now_iso()
+    _write(project_root, data)
+
+
+def set_primary_branch(project_root: Path | str, branch: str) -> None:
+    data = load_ledger(project_root)
+    data["primary_branch"] = str(branch or "")
+    _write(project_root, data)
+
+
+def set_watermark(project_root: Path | str, branch: str, sha: str) -> None:
+    """Record the newest reviewed commit for ``branch`` (scan lower bound)."""
+    data = load_ledger(project_root)
+    data["watermark"][str(branch or "")] = str(sha or "")
+    _write(project_root, data)
+
+
+def get_watermark(project_root: Path | str, branch: str) -> str:
+    """The last reviewed commit recorded for ``branch`` (``""`` when none)."""
+    return str(load_ledger(project_root)["watermark"].get(str(branch or ""), ""))

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli/watch_state.py

@@ -198,6 +198,10 @@ class WatchState:
     model: str = "-"
     selected_sha: str = ""
     current_branch: str = ""
+    # The developer's primary (working) branch — never a ``refactor/*`` sub-branch.
+    # Resolved once at startup; terminal actions restore HEAD here afterwards so
+    # commits are never authored on a sub-branch (which would nest branch names).
+    primary_branch: str = ""
     # Shas the user pressed `[b] back` on: render the review view for them even
     # though their phase is ``finalize`` (docs/43 Part D). Cleared on requeue.
     forced_review: set[str] = field(default_factory=set)
@@ -340,6 +344,38 @@ class WatchState:
             node.run_id = outcome.run_id
 
 
+def hydrate_node_from_ledger(node: "CommitNode", record: dict) -> None:
+    """Rebuild a node's review outcome from a persisted ledger record (Phase 2).
+
+    Lets a relaunched terminal render a previously-analyzed commit without
+    re-running the model. A ``reviewed``/``finalizing``/terminal record restores
+    the node to ``REVIEWED``; anything else (``queued``/``reviewing``/``error``)
+    stays ``QUEUED`` so it is (re)analyzed — errors are intentionally retryable.
+    Open-request counts are intentionally *not* trusted from the ledger (they go
+    stale as requests are resolved); the caller re-derives them live from the RR
+    store when a ``run_id`` is present.
+    """
+    status = str(record.get("status", "") or "")
+    if status in (REVIEWED, "finalizing", "merged", "dropped"):
+        node.state = REVIEWED
+    else:
+        node.state = QUEUED
+    node.run_id = str(record.get("run_id", "") or "") or node.run_id
+    node.gate_status = str(record.get("gate_status", "") or "")
+    node.high_findings = int(record.get("high_findings", 0) or 0)
+    node.rr_count = int(record.get("rr_count", 0) or 0)
+    scope_mode = str(record.get("scope_mode", "") or "")
+    if scope_mode:
+        node.scope_mode = scope_mode
+    changed = int(record.get("changed", 0) or 0)
+    if changed:
+        node.changed = changed
+    node.associated = int(record.get("associated", 0) or 0)
+    intent = str(record.get("intent_summary", "") or "")
+    if intent:
+        node.intent_summary = intent
+
+
 class ReviewOutcomeLike:  # typing helper only; real type lives in review_runner
     error: str
     changed: int

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-cli
-Version: 0.5.8
+Version: 0.6.0
 Summary: Local-first CLI for the refactor platform
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{refactorai_cli-0.5.8 → refactorai_cli-0.6.0}/refactorai_cli.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ refactorai_cli/review_runner.py
 refactorai_cli/runtime_manager.py
 refactorai_cli/settings.py
 refactorai_cli/setup_flow.py
+refactorai_cli/watch_ledger.py
 refactorai_cli/watch_state.py
 refactorai_cli/watch_supervisor.py
 refactorai_cli.egg-info/PKG-INFO