Harden factory-facing drift and contract semantics

Co-authored-by: Andrew <andrewxhill@gmail.com>

Author: andrewxhill-ai

docs/FLOWS.md

@@ -2,6 +2,12 @@
 
 These are the intended operator flows for `mainline` today.
 
+If an agent wrapper, factory daemon, or operator UI parses `--json` output,
+bind only to the documented `v1` machine contract in
+[JSON_CONTRACTS.md](/Users/devrel/Projects/recallnet/mainline/docs/JSON_CONTRACTS.md).
+That document is the compatibility policy. The internal Go structs are not the
+public contract.
+
 ## Solo Developer
 
 Initialize once:

docs/JSON_CONTRACTS.md

@@ -51,6 +51,9 @@ Optional top-level keys:
 - `has_upstream`
 - `is_protected_branch`
 
+`ahead_count` and `behind_count` are exact commit counts relative to the
+upstream ref, not boolean-like drift flags.
+
 `latest_submission` and entries in `active_submissions` extend the durable
 submission record with optional blocked-state diagnostics:
 

internal/git/git.go

@@ -607,27 +607,37 @@ func (e Engine) BranchStatus(branch string, protectedBranch string) (BranchStatu
 		return status, nil
 	}
 
-	branchBehind, err := branchCommit.IsAncestor(upstreamCommit)
+	behind, ahead, err := e.symmetricDifferenceCounts(upstreamRefName.String(), branchRef.Name().String())
 	if err != nil {
 		return BranchStatus{}, err
 	}
-	upstreamBehind, err := upstreamCommit.IsAncestor(branchCommit)
+	status.AheadCount = ahead
+	status.BehindCount = behind
+
+	return status, nil
+}
+
+func (e Engine) symmetricDifferenceCounts(leftRef string, rightRef string) (behind int, ahead int, err error) {
+	layout, err := DiscoverRepositoryLayout(e.RepositoryRoot)
 	if err != nil {
-		return BranchStatus{}, err
+		return 0, 0, err
 	}
 
-	if branchBehind {
-		status.BehindCount = 1
+	cmd := exec.Command("git", "rev-list", "--left-right", "--count", leftRef+"..."+rightRef)
+	cmd.Dir = layout.WorktreeRoot
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return 0, 0, fmt.Errorf("count symmetric difference for %s...%s: %w: %s", leftRef, rightRef, err, strings.TrimSpace(string(output)))
 	}
-	if upstreamBehind {
-		status.AheadCount = 1
+
+	text := strings.TrimSpace(string(output))
+	if _, err := fmt.Sscanf(text, "%d %d", &behind, &ahead); err == nil {
+		return behind, ahead, nil
 	}
-	if !branchBehind && !upstreamBehind {
-		status.AheadCount = 1
-		status.BehindCount = 1
+	if _, err := fmt.Sscanf(text, "%d\t%d", &behind, &ahead); err == nil {
+		return behind, ahead, nil
 	}
-
-	return status, nil
+	return 0, 0, fmt.Errorf("parse symmetric difference counts from %q", text)
 }
 
 // InspectHealth reports doctor-level repository health.

internal/git/git_test.go

@@ -0,0 +1,78 @@
+package git
+
+import (
+	"bytes"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+)
+
+func TestBranchStatusReportsExactAheadBehindCounts(t *testing.T) {
+	remoteDir := filepath.Join(t.TempDir(), "origin.git")
+	runGitCommand(t, t.TempDir(), "git", "init", "--bare", remoteDir)
+
+	repoRoot := t.TempDir()
+	runGitCommand(t, repoRoot, "git", "init", "-b", "main")
+	runGitCommand(t, repoRoot, "git", "config", "user.name", "Test User")
+	runGitCommand(t, repoRoot, "git", "config", "user.email", "test@example.com")
+	runGitCommand(t, repoRoot, "git", "config", "core.hooksPath", ".git/hooks")
+
+	writeFile(t, filepath.Join(repoRoot, "README.md"), "# test\n")
+	runGitCommand(t, repoRoot, "git", "add", "README.md")
+	runGitCommand(t, repoRoot, "git", "commit", "-m", "initial")
+	runGitCommand(t, repoRoot, "git", "remote", "add", "origin", remoteDir)
+	runGitCommand(t, repoRoot, "git", "push", "-u", "origin", "main")
+
+	peerClone := filepath.Join(t.TempDir(), "peer")
+	runGitCommand(t, t.TempDir(), "git", "clone", remoteDir, peerClone)
+	runGitCommand(t, peerClone, "git", "config", "user.name", "Peer User")
+	runGitCommand(t, peerClone, "git", "config", "user.email", "peer@example.com")
+	runGitCommand(t, peerClone, "git", "config", "core.hooksPath", ".git/hooks")
+	writeFile(t, filepath.Join(peerClone, "peer.txt"), "peer\n")
+	runGitCommand(t, peerClone, "git", "add", "peer.txt")
+	runGitCommand(t, peerClone, "git", "commit", "-m", "peer change")
+	runGitCommand(t, peerClone, "git", "push", "origin", "main")
+
+	writeFile(t, filepath.Join(repoRoot, "local-one.txt"), "one\n")
+	runGitCommand(t, repoRoot, "git", "add", "local-one.txt")
+	runGitCommand(t, repoRoot, "git", "commit", "-m", "local one")
+	writeFile(t, filepath.Join(repoRoot, "local-two.txt"), "two\n")
+	runGitCommand(t, repoRoot, "git", "add", "local-two.txt")
+	runGitCommand(t, repoRoot, "git", "commit", "-m", "local two")
+	runGitCommand(t, repoRoot, "git", "fetch", "origin")
+
+	status, err := NewEngine(repoRoot).BranchStatus("main", "main")
+	if err != nil {
+		t.Fatalf("BranchStatus: %v", err)
+	}
+	if status.AheadCount != 2 || status.BehindCount != 1 {
+		t.Fatalf("expected ahead=2 behind=1, got %+v", status)
+	}
+}
+
+func runGitCommand(t *testing.T, dir string, name string, args ...string) string {
+	t.Helper()
+
+	cmd := exec.Command(name, args...)
+	cmd.Dir = dir
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+
+	if err := cmd.Run(); err != nil {
+		t.Fatalf("%s %v failed: %v: %s", name, args, err, stderr.String())
+	}
+
+	return stdout.String()
+}
+
+func writeFile(t *testing.T, path string, contents string) {
+	t.Helper()
+
+	if err := os.WriteFile(path, []byte(contents), 0o644); err != nil {
+		t.Fatalf("WriteFile(%s): %v", path, err)
+	}
+}