feat(lib): capture client-attested build provenance

[max-parke-scale]

Adds agentex.lib.utils.build_provenance — the shared capture util for client-attested build provenance: git coordinates (repo/commit/ref/subpath), a deterministic working_tree_hash over the build inputs (not the tarball), a dirty flag (Go vcs.modified / Nix dirtyRev shape), and normalize_remote. Capture is best-effort and never raises into a build. Also makes the build archive’s member order deterministic via a sorted enumeration shared with the hash.

First of three surfaces for AGX1-418 (Phase 1, client-attested). Provenance is delivered via the build-record sink — source_* columns on POST /v5/builds (Surface C, scaleapi) consumed by the sgpctl + CI uploaders (Surface B, scaleapi/sgp). This PR lands the util + archive determinism where agentex.lib lives; the uploaders/columns follow.

Scope notes

• No build-info.json / runtime sink. An earlier revision wrote build-info.json into the build context for the register_agent() → registration_metadata path. Greptile (T-Rex) correctly flagged it as dead-on-arrival (written to the archive root, which the templates’ Dockerfiles don’t COPY and locate_build_info_path() doesn’t read). It’s also redundant: AgentexCloudDeploy.build_id is an FK to AgentexCloudBuild, so a deployment’s source provenance derives from the build record over that join — the same Build→Deploy edge lineage already traverses. Dropped; can be revived (correctly placed) if a real consumer for deployment-history provenance ever appears.

Identity model

working_tree_hash is always computed (content identity); commit/ref/repo anchor it to source when in a git work tree; dirty records uncommitted changes (None outside git).

Tests

20 provenance unit tests (clean/dirty/untracked/detached-HEAD/no-remote/non-git/monorepo-subpath, hash determinism + one-byte/added/exec-bit/symlink sensitivity, and a never-raises-on-hash-failure guard). ruff/pyright clean; full lib suite green.

🧑‍💻🤖 — posted via Claude Code

Greptile Summary

Introduces agentex.lib.utils.build_provenance — a best-effort utility that captures git coordinates (repo/commit/ref/subpath), a dirty flag, and a deterministic working_tree_hash over build-context files. It also makes the build archive's member order deterministic by sharing a sorted iter_context_files enumeration between the hash and BuildContextManager.zipped().

• build_provenance.py: capture_build_provenance degrades gracefully at each step (non-git dir → content hash only; no remote → omit repo; detached HEAD → tag fallback or None); _safe_working_tree_hash wraps the hash to prevent any I/O failure from aborting a build. normalize_remote correctly strips credentials and scheme from both scp-style and HTTPS URLs.
• agent_manifest.py: zipped() now delegates to iter_context_files, gaining sorted, relpath-stable archive order and correct inclusion of directory symlinks.
• Tests: 20 unit tests cover clean/dirty/untracked/detached-HEAD/no-remote/non-git/monorepo-subpath cases, hash sensitivity (one-byte, added file, exec-bit, symlink target), and the never-raises guard.

Confidence Score: 5/5

Safe to merge — the capture utility is entirely additive, all build paths degrade gracefully on failure, and the archive-determinism change in zipped() is correct.

The change is well-contained: a new utility module with extensive test coverage, plus a small refactor to BuildContextManager.zipped() that makes archive order deterministic. The best-effort design ensures provenance failures cannot abort builds. The one subtle edge case — git status failure silently producing dirty=False — is a minor accuracy concern under unusual runtime conditions but cannot break any build or produce incorrect behavior downstream.

Files Needing Attention: No files require special attention. The three changed files are consistent and well-tested.

Important Files Changed

Filename	Overview
src/agentex/lib/utils/build_provenance.py	New utility capturing git coordinates, content hash, and dirty state for build provenance; well-structured best-effort design with a minor edge case where a git status failure silently records dirty=False.
src/agentex/lib/sdk/config/agent_manifest.py	Replaces manual rglob+is_file loop in zipped() with iter_context_files; makes archive order deterministic and adds symlink inclusion — a correct, intentional behavioral change.
tests/lib/test_build_provenance.py	20 well-designed unit tests covering clean/dirty/untracked/detached-HEAD/no-remote/non-git/monorepo-subpath, hash sensitivity, and the never-raises guard.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[capture_build_provenance\nrepo_path, context_root] --> B[_safe_working_tree_hash\nhash_root]
    B --> B1{Exception?}
    B1 -->|yes| B2[tree_hash = None\nlog warning]
    B1 -->|no| B3[tree_hash = hex digest]
    B2 --> C
    B3 --> C
    C[_git rev-parse --show-toplevel] --> D{repo_root?}
    D -->|None| E[BuildProvenance\nworking_tree_hash only\nbuild_timestamp]
    D -->|Path| F[_git rev-parse HEAD → commit\n_git symbolic-ref HEAD → ref\nfallback: describe --tags --exact-match\n_git remote get-url origin → remote\n_git log -1 → author]
    F --> G{context_root inside repo root?}
    G -->|yes| H[subpath = relative posix path]
    G -->|no / ValueError| I[subpath = None]
    H --> J[_git status --porcelain -- subpath]
    I --> K[_git status --porcelain]
    J --> L{output is not None?}
    K --> L
    L -->|True| M[dirty = True]
    L -->|False| N[dirty = False\nNOTE: also False on git failure]
    M --> O[BuildProvenance\nrepo, commit, ref, subpath,\nworking_tree_hash, dirty,\nauthor, build_timestamp]
    N --> O

Loading

_{Reviews (7): Last reviewed commit: "Merge branch 'next' into maxparke/agx1-4..." | Re-trigger Greptile}

[max-parke-scale]

Addressed both Greptile findings in cf9994d:

1. Ignored files lose hashing — fixed by removing the "skip hash on clean commit" path entirely: working_tree_hash is now always computed over the staged context, so a .gitignored-but-not-.dockerignored file is captured by the content hash regardless of git status. (Identity = the always-present hash; commit anchors it to source. Dedupe is unaffected since the hash is deterministic.)
2. Hash failures abort builds — wrapped the computation in _safe_working_tree_hash, which degrades to None and logs on any error, honoring the “capture never raises into a build” contract.

Also, per design discussion: dirtiness is now a first-class dirty flag (surfaced as source_dirty / dirty) rather than implied by hash-presence — matching Go’s vcs.modified and Nix’s dirtyRev; None outside a git work tree.

🧑‍💻🤖 — posted via Claude Code