Hmbown/CodeWhale · error · PersistenceBacklogError

source provenance command failed

Error message

source provenance command failed: {' '.join(command)}

What it means

This error is raised by the `run` helper inside `current_source_identity()` when a provenance command (`git rev-parse HEAD`, `git status --porcelain`, `rustc --version`, or `cargo --version`) exits with a non-zero status. The script needs a trustworthy snapshot of the current source tree and toolchain before validating a persistence backlog receipt; if any command fails, that snapshot cannot be built, so the check aborts rather than comparing against unverified provenance. The message includes the exact command that failed.

Solutions

  1. Install the Rust toolchain (rustc and cargo) and confirm `rustc --version` and `cargo --version` succeed at the repo root
  2. Run `git rev-parse HEAD` and `git status --porcelain` manually at the repo root to see the underlying git failure
  3. If git reports dubious ownership, run `git config --global --add safe.directory <repo-path>`
  4. Run the script from inside a valid git clone of the repository rather than a plain directory

Example fix

// before (in shell, script fails)
$ python scripts/check-persistence-backlog-budget.py
[persistence-backlog-budget] ERROR: source provenance command failed: rustc --version
// after
$ cargo --version   # install rustup first if missing
$ python scripts/check-persistence-backlog-budget.py
Defensive patterns

Strategy: try-catch

Validate before calling

import subprocess, shutil
def provenance_ready(root):
    for cmd in (["git", "rev-parse", "HEAD"], ["git", "status", "--porcelain"], ["rustc", "--version"], ["cargo", "--version"]):
        if shutil.which(cmd[0]) is None:
            return False
        r = subprocess.run(cmd, cwd=root, capture_output=True, text=True)
        if r.returncode != 0:
            return False
    return True

Type guard

def has_git_repo(root):
    return (root / ".git").exists() and shutil.which("git") is not None

Try / catch

try:
    receipt = check_budget()
except PersistenceBacklogError as e:
    if "source provenance command failed" in str(e):
        install_toolchain_or_fix_git(e)
    else:
        raise

Prevention

When it happens

Trigger: Running `check-persistence-backlog-budget.py` outside a git repository or with a broken HEAD; `rustc` or `cargo` not installed or not on PATH; git refusing due to dubious ownership or a corrupt index; any of the four subprocess calls returning a non-zero returncode.

Common situations: Executing the script in a CI container without the Rust toolchain installed; running it from an exported tarball instead of a git clone; a stale Git safe.directory configuration in Docker; a corrupted .git directory.

Understand the failure class

Background: "git command failed": what it means when a tool shells out to git and git exits non-zero — this error's family across 21 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/36d81fdea551ee77. Report an issue: GitHub.

Appendix: source

Thrown at scripts/check-persistence-backlog-budget.py:119

def validate_frozen_field(field: str, value: Any, expected: Any) -> None:
    if type(value) is not type(expected) or value != expected:
        raise PersistenceBacklogError(
            f"receipt {field} must remain {expected!r}, got {value!r}"
        )


def current_source_identity() -> dict[str, Any]:
    def run(command: list[str]) -> str:
        result = subprocess.run(
            command,
            cwd=ROOT,
            text=True,
            capture_output=True,
            check=False,
        )
        if result.returncode != 0:
            raise PersistenceBacklogError(
                f"source provenance command failed: {' '.join(command)}"
            )
        return result.stdout.strip()

    return {
        "source_sha": run(["git", "rev-parse", "HEAD"]),
        "source_dirty": bool(
            run(["git", "status", "--porcelain", "--untracked-files=normal"])
        ),
        "rustc_version": run(["rustc", "--version"]),
        "cargo_version": run(["cargo", "--version"]),
        "build_profile": "test",
        "sample_count": 1,
    }


def validate_receipt(
    receipt: dict[str, Any],

View on GitHub (pinned to 433685b202)