tmux-video-evidence

Tmux Video Evidence for Agent Work Verification

Purpose

Record terminal-based evidence videos that another agent (or human) can review to verify that code changes, test results, and deployments are legitimate. The key principle: the video must tie test output to a specific git commit and prove no tampering occurred during recording.

Prerequisites

# Required
brew install asciinema   # Terminal recorder (outputs .cast files)
brew install agg         # Converts .cast → .gif for embedding in docs/PRs

Evidence Script Template

Create a script at /tmp/<work_name>_evidence.sh:

#!/bin/bash
# Evidence Recording Script — <PR/Work Item>
set -e

REPO_ROOT="<absolute path to repo>"
cd "$REPO_ROOT"

echo "╔═══════════════════════════════════════════════════════╗"
echo "║  <Title> — Evidence Capture                          ║"
echo "║  Recorded: $(date -u '+%Y-%m-%dT%H:%M:%SZ')                 ║"
echo "╚═══════════════════════════════════════════════════════╝"
echo ""

# ── 1. Git Provenance (MANDATORY — ties ALL output to this commit) ──
echo "━━━━━━━ 1. GIT PROVENANCE ━━━━━━━"
HEAD_SHA=$(git rev-parse HEAD)
BRANCH=$(git branch --show-current)
echo "  HEAD SHA:  $HEAD_SHA"
echo "  Branch:    $BRANCH"
echo "  Merge-base vs main: $(git merge-base HEAD origin/main)"
echo "  Commits ahead of main: $(git rev-list --count origin/main..HEAD)"
echo ""

# ── 2. Commit log ──
echo "━━━━━━━ 2. COMMIT LOG ━━━━━━━"
git log --oneline origin/main..HEAD
echo ""

# ── 3. Actual code diffs (not just --stat) ──
echo "━━━━━━━ 3. CODE DIFFS ━━━━━━━"
echo "--- diff --stat ---"
git diff --stat origin/main...HEAD
echo ""
echo "--- key file diffs (abbreviated) ---"
# Show actual diff for each important file:
for f in <list important changed files>; do
  echo "[$f]:"
  git diff origin/main...HEAD -- "$f" | head -60
  echo ""
done

# ── 4. PR/Work Item verification ──
echo "━━━━━━━ 4. PR STATUS ━━━━━━━"
gh pr view <PR_NUMBER> --json number,title,url,headRefName,state \
  -q '{number, title, url, headRefName, state}'
echo ""

# ── 5. Live test execution ──
echo "━━━━━━━ 5. LIVE TEST EXECUTION ━━━━━━━"
echo "Running tests against commit $HEAD_SHA..."

# Run your test suites:
cd "$REPO_ROOT/<package>"
npm test 2>&1 | grep -E "(PASS|FAIL|Test Suites|Tests:|Time:)"
echo ""

# ── 6. Post-test SHA check (MANDATORY — proves no commit change) ──
echo "━━━━━━━ 6. POST-TEST SHA VERIFICATION ━━━━━━━"
cd "$REPO_ROOT"
POST_SHA=$(git rev-parse HEAD)
echo "  Pre-test SHA:  $HEAD_SHA"
echo "  Post-test SHA: $POST_SHA"
if [ "$HEAD_SHA" = "$POST_SHA" ]; then
  echo "  ✅ SHA MATCH — tests ran against the claimed commit"
else
  echo "  ❌ SHA MISMATCH — working tree changed during tests!"
fi
echo "  Working tree clean: $(git status --porcelain | wc -l | tr -d ' ') uncommitted changes"

echo ""
echo "╔═══════════════════════════════════════════════════╗"
echo "║  EVIDENCE COMPLETE — Commit: $HEAD_SHA  ║"
echo "╚═══════════════════════════════════════════════════╝"