From 03530f9bf47c06ce95005a79b2820741e8575637 Mon Sep 17 00:00:00 2001
From: Christopher Tso <christso@gmail.com>
Date: Wed, 24 Jun 2026 16:25:51 +0200
Subject: [PATCH 1/4] feat(results): replace force-push with artifact-aware
 auto-merge sync loop

Phase 0 (av-raf.1): register a tiny dependency-free `agentv-json` 3-way JSON
merge driver and mirror union/agentv-json merge attributes into the AgentV-owned
results checkout (committed `.gitattributes` for portability plus repo-local
`info/attributes` so local merges always apply the drivers). Append-only run
indexes union-merge; editable tag/feedback overlays set/field-union, and a
genuine scalar conflict falls through to a human merge.

Phase 1 (av-raf.2): rewrite resolveResultBranchPushConflict as a bounded
fetch -> merge -> push loop. Fast-forward when possible, otherwise commit a real
3-way merge (working-tree merge on a checked-out branch, merge-tree+update-ref on
a detached storage branch) and fast-forward the canonical branch onto it; retry
benign push races. A genuine conflict aborts the merge and returns a distinct
`needs_human_merge` blocked outcome. Never force-pushes and never creates a
backup ref. `push_conflict_policy: backup_and_force_push` is deprecated: it is
kept for config back-compat but now auto-merges (no force) and warns once.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 packages/core/src/evaluation/results-repo.ts | 583 +++++++++++++++----
 1 file changed, 484 insertions(+), 99 deletions(-)

diff --git a/packages/core/src/evaluation/results-repo.ts b/packages/core/src/evaluation/results-repo.ts
index 3f1d070b9..25ea43d79 100644
--- a/packages/core/src/evaluation/results-repo.ts
+++ b/packages/core/src/evaluation/results-repo.ts
@@ -66,6 +66,127 @@ const RESULTS_REPO_GENESIS_MESSAGE = 'chore(results): initialize AgentV results
 const RESULTS_REPO_GENESIS_DATE = '@0 +0000';
 const RESULT_INDEX_FILENAME = 'index.jsonl';
 
+// Artifact-aware merge config for the AgentV-owned results checkout. These two
+// pieces let `git merge` reconcile concurrent result writes automatically so
+// results sync never has to force-push (see resolveResultBranchPushConflict):
+//   - `.gitattributes` (committed on the results branch) maps the append-only
+//     run index to git's stock `union` driver and the editable JSON overlay to
+//     our `agentv-json` driver.
+//   - `merge.agentv-json.driver` (registered once in the checkout's local git
+//     config) points at a tiny 3-way JSON set/field union script.
+// Run bundles under runs/<exp>/<ts>/** are uniquely pathed, so a 3-way merge
+// never conflicts on them and they need no attribute.
+const RESULTS_REPO_GITATTRIBUTES_FILE = '.gitattributes';
+const RESULTS_REPO_GITATTRIBUTES_CONTENT = `# Managed by AgentV. Artifact-aware merge so results sync never force-pushes.
+# Append-only run index: union concurrent appends (lines are orthogonal).
+index.jsonl merge=union
+# Editable run overlay (tags/feedback): 3-way JSON set/field union via the
+# agentv-json driver; a genuine scalar conflict falls through to a human merge.
+metadata/runs/**/*.json merge=agentv-json
+`;
+const RESULTS_JSON_MERGE_DRIVER_NAME = 'agentv-json';
+// Materialized into the results checkout's git dir and invoked by git as
+// `node <script> %O %A %B %P`. Kept dependency-free and self-describing so it
+// runs under any Node without bundling. To extend the overlay merge, add cases
+// to merge3 below (e.g. new regenerable bookkeeping fields).
+const RESULTS_JSON_MERGE_DRIVER_SCRIPT = `#!/usr/bin/env node
+// AgentV results overlay merge driver (merge=agentv-json).
+//
+// Performs a 3-way merge of AgentV's editable JSON overlay files (run tags /
+// feedback). Tag lists merge as a 3-way set so concurrent add/remove are
+// commutative; bookkeeping scalars that always differ between writers
+// (updated_at, tag_revision) are regenerated to the larger value instead of
+// conflicting. Any other genuinely diverging scalar exits non-zero, leaving the
+// file conflicted so the caller can route it to a human GitHub merge.
+//
+// Invoked by git as: node json-merge-driver.mjs %O %A %B %P
+//   %O ancestor, %A current (overwritten with the result), %B other, %P path.
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const [, , ancestorFile, currentFile, otherFile] = process.argv;
+const CONFLICT = Symbol('conflict');
+// Scalars that legitimately differ on every write and carry no merge meaning.
+const REGENERABLE_SCALARS = new Set(['updated_at', 'tag_revision']);
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+function isPrimitiveArray(value) {
+  return (
+    Array.isArray(value) &&
+    value.every((entry) => entry === null || ['string', 'number', 'boolean'].includes(typeof entry))
+  );
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeSet(base, a, b) {
+  const baseSet = new Set((isPrimitiveArray(base) ? base : []).map(String));
+  const aSet = new Set(a.map(String));
+  const bSet = new Set(b.map(String));
+  const removed = new Set();
+  for (const value of baseSet) {
+    if (!aSet.has(value) || !bSet.has(value)) removed.add(value);
+  }
+  const merged = [];
+  const seen = new Set();
+  for (const value of [...a, ...b]) {
+    const key = String(value);
+    if (!removed.has(key) && !seen.has(key)) {
+      seen.add(key);
+      merged.push(value);
+    }
+  }
+  return merged;
+}
+
+function merge3(base, a, b, key) {
+  if (JSON.stringify(a) === JSON.stringify(b)) return a;
+  if (JSON.stringify(a) === JSON.stringify(base)) return b;
+  if (JSON.stringify(b) === JSON.stringify(base)) return a;
+  if (isPrimitiveArray(a) && isPrimitiveArray(b)) return mergeSet(base, a, b);
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = new Set([
+      ...Object.keys(a),
+      ...Object.keys(b),
+      ...(isPlainObject(base) ? Object.keys(base) : []),
+    ]);
+    const out = {};
+    for (const childKey of keys) {
+      const merged = merge3(
+        isPlainObject(base) ? base[childKey] : undefined,
+        a[childKey],
+        b[childKey],
+        childKey,
+      );
+      if (merged === CONFLICT) return CONFLICT;
+      if (merged !== undefined) out[childKey] = merged;
+    }
+    return out;
+  }
+  if (REGENERABLE_SCALARS.has(key)) {
+    return [a, b].filter((value) => value !== undefined).sort().pop();
+  }
+  return CONFLICT;
+}
+
+const ancestor = readJson(ancestorFile) ?? {};
+const current = readJson(currentFile);
+const other = readJson(otherFile);
+if (current === undefined || other === undefined) process.exit(1);
+const result = merge3(ancestor, current, other, '');
+if (result === CONFLICT) process.exit(1);
+writeFileSync(currentFile, \`\${JSON.stringify(result, null, 2)}\\n\`);
+process.exit(0);
+`;
+
 export interface ResultsRepoLocalPaths {
   readonly rootDir: string;
   readonly repoDir: string;
@@ -81,6 +202,7 @@ export type ResultsRepoSyncStatus =
   | 'dirty'
   | 'conflicted'
   | 'push_conflict'
+  | 'needs_human_merge'
   | 'syncing';
 
 export interface ResultsRepoStatus {
@@ -613,6 +735,131 @@ async function resolveGitTopLevel(repoDir: string): Promise<string> {
   return stdout.trim() || repoDir;
 }
 
+// Register the artifact-aware `agentv-json` merge driver in the AgentV-owned
+// results checkout. This is a one-time, idempotent local-config write (never a
+// global/user config change) plus materializing the dependency-free driver
+// script into the checkout's git dir. `.gitattributes` on the branch maps the
+// overlay paths to this driver; together they let resolveResultBranchPushConflict
+// auto-merge concurrent writes without ever force-pushing.
+async function ensureResultsMergeConfig(repoDir: string): Promise<void> {
+  let gitDir: string;
+  try {
+    const { stdout } = await runGit(['rev-parse', '--git-common-dir'], { cwd: repoDir });
+    const resolved = stdout.trim();
+    gitDir = resolved
+      ? path.isAbsolute(resolved)
+        ? resolved
+        : path.join(repoDir, resolved)
+      : path.join(repoDir, '.git');
+  } catch {
+    return;
+  }
+
+  const driverScriptPath = path.join(gitDir, 'agentv', 'json-merge-driver.mjs');
+  let scriptCurrent = false;
+  try {
+    scriptCurrent = readFileSync(driverScriptPath, 'utf8') === RESULTS_JSON_MERGE_DRIVER_SCRIPT;
+  } catch {
+    scriptCurrent = false;
+  }
+  if (!scriptCurrent) {
+    mkdirSync(path.dirname(driverScriptPath), { recursive: true });
+    writeFileSync(driverScriptPath, RESULTS_JSON_MERGE_DRIVER_SCRIPT, { mode: 0o755 });
+  }
+
+  const driverCommand = `node ${JSON.stringify(driverScriptPath)} %O %A %B %P`;
+  await runGit(
+    ['config', `merge.${RESULTS_JSON_MERGE_DRIVER_NAME}.name`, 'AgentV results overlay JSON union'],
+    { cwd: repoDir, check: false },
+  );
+  await runGit(['config', `merge.${RESULTS_JSON_MERGE_DRIVER_NAME}.driver`, driverCommand], {
+    cwd: repoDir,
+    check: false,
+  });
+
+  // Also mirror the merge attributes into the repo-local `info/attributes`. The
+  // committed `.gitattributes` makes the drivers portable to other clients, but
+  // info/attributes guarantees they apply to *this* checkout's merges even on
+  // branches committed before `.gitattributes` existed, and for both the
+  // working-tree merge and the detached `merge-tree` paths.
+  writeResultsInfoAttributes(gitDir);
+}
+
+const RESULTS_INFO_ATTRIBUTES_BEGIN = '# >>> agentv results merge attributes >>>';
+const RESULTS_INFO_ATTRIBUTES_END = '# <<< agentv results merge attributes <<<';
+
+// Idempotently install AgentV's merge attributes into `<git-dir>/info/attributes`
+// inside a managed marker block, preserving any unrelated lines already there.
+function writeResultsInfoAttributes(gitDir: string): void {
+  const infoDir = path.join(gitDir, 'info');
+  const attributesPath = path.join(infoDir, 'attributes');
+  const managedBlock = `${RESULTS_INFO_ATTRIBUTES_BEGIN}\n${RESULTS_REPO_GITATTRIBUTES_CONTENT.trimEnd()}\n${RESULTS_INFO_ATTRIBUTES_END}\n`;
+
+  let existing = '';
+  try {
+    existing = readFileSync(attributesPath, 'utf8');
+  } catch {
+    existing = '';
+  }
+
+  const blockPattern = new RegExp(
+    `${escapeRegExp(RESULTS_INFO_ATTRIBUTES_BEGIN)}[\\s\\S]*?${escapeRegExp(
+      RESULTS_INFO_ATTRIBUTES_END,
+    )}\\n?`,
+  );
+  const withoutManaged = existing.replace(blockPattern, '');
+  const next =
+    withoutManaged.length > 0 && !withoutManaged.endsWith('\n')
+      ? `${withoutManaged}\n${managedBlock}`
+      : `${withoutManaged}${managedBlock}`;
+  if (next === existing) {
+    return;
+  }
+  mkdirSync(infoDir, { recursive: true });
+  writeFileSync(attributesPath, next);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Inject the managed `.gitattributes` blob into a temporary git index so every
+// results commit carries it. Merge drivers read attributes from the trees being
+// merged, so the file must live on the branch, not just in repo config. Skips
+// the write when the base tree already has identical content, preserving the
+// "tree unchanged" no-op detection in the commit helpers.
+async function addResultsGitattributesToIndex(
+  repoDir: string,
+  indexEnv: NodeJS.ProcessEnv,
+): Promise<void> {
+  const { stdout: existing } = await runGit(
+    ['cat-file', '-p', `:0:${RESULTS_REPO_GITATTRIBUTES_FILE}`],
+    { cwd: repoDir, env: indexEnv, check: false },
+  );
+  if (existing === RESULTS_REPO_GITATTRIBUTES_CONTENT) {
+    return;
+  }
+  const scratchDir = mkdtempSync(path.join(os.tmpdir(), 'agentv-results-attrs-'));
+  try {
+    const scratchFile = path.join(scratchDir, RESULTS_REPO_GITATTRIBUTES_FILE);
+    writeFileSync(scratchFile, RESULTS_REPO_GITATTRIBUTES_CONTENT);
+    const { stdout: blob } = await runGit(['hash-object', '-w', '--no-filters', scratchFile], {
+      cwd: repoDir,
+    });
+    await runGit(
+      [
+        'update-index',
+        '--add',
+        '--cacheinfo',
+        `100644,${blob.trim()},${RESULTS_REPO_GITATTRIBUTES_FILE}`,
+      ],
+      { cwd: repoDir, env: indexEnv },
+    );
+  } finally {
+    rmSync(scratchDir, { recursive: true, force: true });
+  }
+}
+
 async function ensureResultsRepoRemote(
   repoDir: string,
   config: NormalizedResultsConfig,
@@ -663,7 +910,9 @@ export async function ensureResultsRepoClone(config: ResultsConfig): Promise<str
     if (!(await isGitRepository(normalized.repo_path))) {
       throw new Error(`Results repo_path is not a git repository: ${normalized.repo_path}`);
     }
-    return resolveGitTopLevel(normalized.repo_path);
+    const topLevel = await resolveGitTopLevel(normalized.repo_path);
+    await ensureResultsMergeConfig(topLevel);
+    return topLevel;
   }
 
   const cachePaths = getResultsRepoLocalPaths(normalized.repo);
@@ -684,6 +933,7 @@ export async function ensureResultsRepoClone(config: ResultsConfig): Promise<str
         cloneDir,
       ]);
       await ensureResultsRepoRemote(cloneDir, normalized);
+      await ensureResultsMergeConfig(cloneDir);
       return cloneDir;
     } catch (error) {
       updateStatusFile(normalized, { last_error: withFriendlyGitHubAuthError(error).message });
@@ -696,6 +946,7 @@ export async function ensureResultsRepoClone(config: ResultsConfig): Promise<str
   }
 
   await ensureResultsRepoRemote(cloneDir, normalized);
+  await ensureResultsMergeConfig(cloneDir);
   return cloneDir;
 }
 
@@ -1162,6 +1413,7 @@ type ResultsBranchPushOutcome =
       readonly blocked: true;
       readonly blockReason: string;
       readonly details: ResultsBranchPushDetails;
+      readonly syncStatus?: ResultsRepoSyncStatus;
     };
 
 class ResultsBranchPushConflictError extends Error {
@@ -1234,16 +1486,19 @@ function withPushConflictStatus(
     readonly pullPerformed: boolean;
     readonly pushPerformed: boolean;
     readonly commitCreated: boolean;
+    readonly syncStatus?: ResultsRepoSyncStatus;
   },
 ): ResultsRepoStatus {
   return withBlockedStatus(
     {
       ...status,
-      sync_status: 'push_conflict',
+      sync_status: flags.syncStatus ?? 'push_conflict',
     },
     blockReason,
     {
-      ...flags,
+      pullPerformed: flags.pullPerformed,
+      pushPerformed: flags.pushPerformed,
+      commitCreated: flags.commitCreated,
       pushDetails: details,
     },
   );
@@ -1269,7 +1524,10 @@ function withActionFlags(
 }
 
 function isSafeResultsRepoPath(p: string): boolean {
-  return RESULTS_REPO_TRACKED_DIRS.some((dir) => p === dir || p.startsWith(`${dir}/`));
+  return (
+    p === RESULTS_REPO_GITATTRIBUTES_FILE ||
+    RESULTS_REPO_TRACKED_DIRS.some((dir) => p === dir || p.startsWith(`${dir}/`))
+  );
 }
 
 // git errors on a pathspec that matches nothing, so when staging AgentV's result
@@ -1322,26 +1580,8 @@ function getPushTargetBranch(
   return upstream?.startsWith(prefix) ? upstream.slice(prefix.length) : baseBranch;
 }
 
-function timestampForBackupRef(date = new Date()): string {
-  const pad = (value: number) => String(value).padStart(2, '0');
-  return `${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}T${pad(
-    date.getUTCHours(),
-  )}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}Z`;
-}
-
-function slugifyBackupTargetBranch(branch: string): string {
-  return (
-    branch
-      .trim()
-      .replace(/[^A-Za-z0-9._-]+/g, '-')
-      .replace(/^-+|-+$/g, '') || 'results'
-  );
-}
-
-function buildResultsBackupRef(targetBranch: string, remoteCommit: string): string {
-  return `agentv/backups/${timestampForBackupRef()}-${slugifyBackupTargetBranch(
-    targetBranch,
-  )}-${remoteCommit.slice(0, 7)}`;
+function formatShortSha(sha: string | undefined): string {
+  return sha ? sha.slice(0, 12) : 'unknown';
 }
 
 async function getCommitSha(repoDir: string, ref: string | undefined): Promise<string | undefined> {
@@ -1367,103 +1607,242 @@ function isNonFastForwardPushError(error: unknown): boolean {
   );
 }
 
-function formatShortSha(sha: string | undefined): string {
-  return sha ? sha.slice(0, 12) : 'unknown';
+// Bounded optimistic retry for the fetch → merge → push loop. Covers the benign
+// race where another writer advances the remote between our fetch and push.
+const RESULTS_PUSH_MERGE_MAX_ATTEMPTS = 5;
+
+let warnedForcePushPolicyDeprecation = false;
+// `backup_and_force_push` is retained for config back-compat but no longer force
+// pushes. Layer 1's auto-merge loop handles the common case and genuine
+// conflicts go to a human GitHub merge, so the policy is a no-op alias for the
+// safe default. Warn once per process so existing configs surface the change.
+function warnDeprecatedForcePushPolicyOnce(): void {
+  if (warnedForcePushPolicyDeprecation) {
+    return;
+  }
+  warnedForcePushPolicyDeprecation = true;
+  console.warn(
+    "[agentv] results.sync.push_conflict_policy: 'backup_and_force_push' is deprecated and no " +
+      'longer force-pushes. Results sync now auto-merges concurrent writes and routes genuine ' +
+      'conflicts to a human GitHub merge.',
+  );
 }
 
-function buildBlockedPushConflictReason(details: ResultsBranchPushDetails): string {
-  return `Results branch push conflict on ${details.targetBranch}: remote ${formatShortSha(
-    details.remoteCommit,
-  )}, local ${formatShortSha(details.localCommit)}. Configure results.sync.push_conflict_policy: backup_and_force_push to back up the remote ref before replacing it.`;
+async function isAncestorCommit(
+  repoDir: string,
+  ancestor: string,
+  descendant: string,
+): Promise<boolean> {
+  const { exitCode } = await runGit(['merge-base', '--is-ancestor', ancestor, descendant], {
+    cwd: repoDir,
+    check: false,
+  });
+  return exitCode === 0;
 }
 
+async function getMergeBaseCommit(
+  repoDir: string,
+  a: string,
+  b: string,
+): Promise<string | undefined> {
+  const { stdout, exitCode } = await runGit(['merge-base', a, b], { cwd: repoDir, check: false });
+  const sha = stdout.trim();
+  return exitCode === 0 && sha.length > 0 ? sha : undefined;
+}
+
+function buildNeedsHumanMergeReason(
+  targetBranch: string,
+  remoteCommit: string | undefined,
+  localCommit: string | undefined,
+): string {
+  return `Results branch ${targetBranch} diverged from the remote and could not be auto-merged: a genuine content conflict in the editable overlay remains (remote ${formatShortSha(
+    remoteCommit,
+  )}, local ${formatShortSha(
+    localCommit,
+  )}). The remote branch is unchanged and no history was rewritten; resolve it with a GitHub pull request.`;
+}
+
+// Merge `remoteCommit` into the currently checked-out branch via a real
+// `git merge`, so the working tree and index advance together (the ref-only
+// path uses merge-tree + update-ref instead). Returns the merge exit code; a
+// non-zero code means git left a conflict, which the caller aborts.
+async function mergeRemoteIntoCheckedOutBranch(
+  repoDir: string,
+  remoteCommit: string,
+): Promise<number> {
+  const args = ['merge', '--no-edit', '-m', 'chore(results): merge remote results', remoteCommit];
+  let result = await runGit(args, {
+    cwd: repoDir,
+    check: false,
+    env: configuredGitCommitIdentityEnv(),
+  });
+  if (result.exitCode !== 0 && isMissingGitIdentityError({ stderr: result.stderr })) {
+    await runGit(['merge', '--abort'], { cwd: repoDir, check: false });
+    result = await runGit(args, {
+      cwd: repoDir,
+      check: false,
+      env: { ...configuredGitCommitIdentityEnv(), ...fallbackResultsRepoCommitEnv() },
+    });
+  }
+  return result.exitCode;
+}
+
+// Layer 1 of the no-force-push results sync (see
+// docs/plans/2026-06-24-001-feat-conflict-free-results-sync-plan.md). A bounded
+// fetch → merge → push loop: fast-forward when possible, otherwise commit a real
+// 3-way merge using the artifact-aware drivers (union index, agentv-json
+// overlay) and fast-forward the canonical branch onto it. A genuine overlay
+// conflict returns a `needs_human_merge` blocked outcome — never a force push.
 async function resolveResultBranchPushConflict(params: {
   readonly normalized: StorageBranchResultsConfig;
   readonly repoDir: string;
   readonly targetBranch: string;
   readonly sourceRef: string;
 }): Promise<ResultsBranchPushOutcome> {
-  await fetchResultsRepo(params.repoDir, params.normalized.remote, params.targetBranch);
-  const remoteRef = remoteBranchRef(params.targetBranch, params.normalized.remote);
-  const remoteCommit = await getCommitSha(params.repoDir, remoteRef);
-  const localCommit = await getCommitSha(params.repoDir, params.sourceRef);
-  const baseDetails: ResultsBranchPushDetails = {
+  if (params.normalized.push_conflict_policy === 'backup_and_force_push') {
+    warnDeprecatedForcePushPolicyOnce();
+  }
+  await ensureResultsMergeConfig(params.repoDir);
+
+  const { repoDir, targetBranch } = params;
+  const remote = params.normalized.remote;
+  const localRef = params.sourceRef;
+  const remoteRef = remoteBranchRef(targetBranch, remote);
+  // When the caller hands us `HEAD`, the canonical branch is checked out, so we
+  // must advance the working tree too (real `git merge`). The storage-branch
+  // path hands us `refs/heads/<branch>` with a detached HEAD, where we update
+  // the ref directly via merge-tree to avoid touching any working tree.
+  const branchCheckedOut = params.sourceRef === 'HEAD';
+
+  let lastDetails: ResultsBranchPushDetails = {
     pushConflictPolicy: params.normalized.push_conflict_policy,
-    targetBranch: params.targetBranch,
-    ...(remoteCommit !== undefined && {
-      remoteCommit,
-      previousRemoteCommit: remoteCommit,
-      leaseCommit: remoteCommit,
-    }),
-    ...(localCommit !== undefined && { localCommit }),
+    targetBranch,
   };
 
-  if (!remoteCommit) {
-    return {
-      blocked: true,
-      blockReason: `Results branch push conflict on ${params.targetBranch}: remote commit could not be resolved after fetch`,
-      details: baseDetails,
+  for (let attempt = 1; attempt <= RESULTS_PUSH_MERGE_MAX_ATTEMPTS; attempt += 1) {
+    await fetchResultsRepo(repoDir, remote, targetBranch);
+    const remoteCommit = await getCommitSha(repoDir, remoteRef);
+    const localCommit = await getCommitSha(repoDir, localRef);
+    const details: ResultsBranchPushDetails = {
+      pushConflictPolicy: params.normalized.push_conflict_policy,
+      targetBranch,
+      ...(remoteCommit !== undefined && { remoteCommit, previousRemoteCommit: remoteCommit }),
+      ...(localCommit !== undefined && { localCommit }),
     };
-  }
+    lastDetails = details;
 
-  if (params.normalized.push_conflict_policy === 'block') {
-    return {
-      blocked: true,
-      blockReason: buildBlockedPushConflictReason(baseDetails),
-      details: baseDetails,
-    };
-  }
+    if (!remoteCommit) {
+      return {
+        blocked: true,
+        blockReason: `Results branch push conflict on ${targetBranch}: remote commit could not be resolved after fetch`,
+        details,
+        syncStatus: 'push_conflict',
+      };
+    }
+    if (!localCommit) {
+      return {
+        blocked: true,
+        blockReason: `Results branch push conflict on ${targetBranch}: local commit could not be resolved`,
+        details,
+        syncStatus: 'push_conflict',
+      };
+    }
 
-  const backupRef = buildResultsBackupRef(params.targetBranch, remoteCommit);
-  const backupDetails: ResultsBranchPushDetails = {
-    ...baseDetails,
-    backupRef,
-    backupCommit: remoteCommit,
-  };
+    // Remote already contains our work: fast-forward to it and stop.
+    if (await isAncestorCommit(repoDir, localCommit, remoteCommit)) {
+      if (branchCheckedOut) {
+        await runGit(['merge', '--ff-only', remoteCommit], { cwd: repoDir, check: false });
+      } else {
+        await runGit(['update-ref', localRef, remoteCommit, localCommit], {
+          cwd: repoDir,
+          check: false,
+        });
+      }
+      return { blocked: false, details };
+    }
+
+    let pushSpec = branchCheckedOut ? 'HEAD' : localCommit;
+    // Diverged (neither side is an ancestor): commit a real 3-way merge using
+    // the artifact-aware drivers. If `git merge` reports a genuine conflict, no
+    // history is rewritten and we route to a human GitHub merge.
+    if (!(await isAncestorCommit(repoDir, remoteCommit, localCommit))) {
+      if (branchCheckedOut) {
+        const exitCode = await mergeRemoteIntoCheckedOutBranch(repoDir, remoteCommit);
+        if (exitCode !== 0) {
+          await runGit(['merge', '--abort'], { cwd: repoDir, check: false });
+          return {
+            blocked: true,
+            blockReason: buildNeedsHumanMergeReason(targetBranch, remoteCommit, localCommit),
+            details,
+            syncStatus: 'needs_human_merge',
+          };
+        }
+        pushSpec = 'HEAD';
+      } else {
+        const base = await getMergeBaseCommit(repoDir, localCommit, remoteCommit);
+        if (!base) {
+          return {
+            blocked: true,
+            blockReason: buildNeedsHumanMergeReason(targetBranch, remoteCommit, localCommit),
+            details,
+            syncStatus: 'needs_human_merge',
+          };
+        }
+        const merge = await runGit(
+          ['merge-tree', '--write-tree', `--merge-base=${base}`, localCommit, remoteCommit],
+          { cwd: repoDir, check: false },
+        );
+        const mergedTree = merge.stdout.trim().split(/\r?\n/)[0]?.trim();
+        if (merge.exitCode !== 0 || !mergedTree) {
+          return {
+            blocked: true,
+            blockReason: buildNeedsHumanMergeReason(targetBranch, remoteCommit, localCommit),
+            details,
+            syncStatus: 'needs_human_merge',
+          };
+        }
+        const { stdout: mergeCommitOut } = await runGitWithFallbackCommitIdentity(
+          [
+            'commit-tree',
+            mergedTree,
+            '-p',
+            localCommit,
+            '-p',
+            remoteCommit,
+            '-m',
+            'chore(results): merge remote results',
+          ],
+          { cwd: repoDir },
+        );
+        pushSpec = mergeCommitOut.trim();
+        await runGit(['update-ref', localRef, pushSpec, localCommit], { cwd: repoDir });
+      }
+    }
 
-  try {
-    await assertValidResultsBranchName(params.repoDir, backupRef);
-    await runGit(
-      ['push', '--porcelain', params.normalized.remote, `${remoteCommit}:refs/heads/${backupRef}`],
-      { cwd: params.repoDir },
-    );
-  } catch (error) {
-    return {
-      blocked: true,
-      blockReason: `Results branch backup creation failed for ${params.targetBranch} at ${formatShortSha(
-        remoteCommit,
-      )}: ${getStatusMessage(error)}`,
-      details: backupDetails,
-    };
-  }
+    try {
+      await runGit(['push', '--porcelain', remote, `${pushSpec}:refs/heads/${targetBranch}`], {
+        cwd: repoDir,
+      });
+    } catch (error) {
+      if (isNonFastForwardPushError(error)) {
+        // Remote advanced between fetch and push; retry the loop.
+        continue;
+      }
+      throw error;
+    }
 
-  try {
-    await runGit(
-      [
-        'push',
-        '--porcelain',
-        `--force-with-lease=refs/heads/${params.targetBranch}:${remoteCommit}`,
-        params.normalized.remote,
-        `${params.sourceRef}:refs/heads/${params.targetBranch}`,
-      ],
-      { cwd: params.repoDir },
-    );
-  } catch (error) {
+    const pushedCommit = (await getCommitSha(repoDir, pushSpec)) ?? localCommit;
     return {
-      blocked: true,
-      blockReason: `Results branch force push lease failed for ${params.targetBranch}; remote changed after backup ${backupRef} was created with lease ${formatShortSha(
-        remoteCommit,
-      )}: ${getStatusMessage(error)}`,
-      details: backupDetails,
+      blocked: false,
+      details: { ...details, localCommit: pushedCommit },
     };
   }
 
   return {
-    blocked: false,
-    details: {
-      ...backupDetails,
-      ...(localCommit !== undefined && { forcePushedCommit: localCommit }),
-    },
+    blocked: true,
+    blockReason: `Results branch ${targetBranch} could not be reconciled after ${RESULTS_PUSH_MERGE_MAX_ATTEMPTS} attempts because the remote kept advancing; retry sync. The remote branch is unchanged.`,
+    details: lastDetails,
+    syncStatus: 'needs_human_merge',
   };
 }
 
@@ -1679,6 +2058,7 @@ export async function syncResultsRepoForProject(config: ResultsConfig): Promise<
             pullPerformed,
             pushPerformed,
             commitCreated,
+            syncStatus: outcome.syncStatus,
           });
         }
         pushPerformed = true;
@@ -1801,6 +2181,7 @@ export async function syncResultsRepoForProject(config: ResultsConfig): Promise<
                     pullPerformed,
                     pushPerformed,
                     commitCreated,
+                    syncStatus: outcome.syncStatus,
                   });
                 }
               } else {
@@ -1942,6 +2323,7 @@ export async function syncResultsRepoForProject(config: ResultsConfig): Promise<
           pullPerformed,
           pushPerformed,
           commitCreated,
+          syncStatus: outcome.syncStatus,
         });
       }
       pushPerformed = true;
@@ -2034,6 +2416,7 @@ export async function syncResultsRepoForProject(config: ResultsConfig): Promise<
               pullPerformed,
               pushPerformed,
               commitCreated,
+              syncStatus: outcome.syncStatus,
             });
           }
         } else {
@@ -2611,6 +2994,7 @@ async function commitStorageBranchWorktreePaths(params: {
     } else {
       await runGit(['read-tree', '--empty'], { cwd: params.repoDir, env: indexEnv });
     }
+    await addResultsGitattributesToIndex(params.repoDir, indexEnv);
 
     for (const gitPath of paths) {
       const sourcePath = path.join(params.repoDir, ...gitPath.split('/'));
@@ -2730,6 +3114,7 @@ async function commitResultsRunWithTemporaryIndex(params: {
     } else {
       await runGit(['read-tree', '--empty'], { cwd: params.repoDir, env: indexEnv });
     }
+    await addResultsGitattributesToIndex(params.repoDir, indexEnv);
 
     const existingPaths = await getExistingRunTreePaths(
       params.repoDir,
@@ -2832,7 +3217,7 @@ function buildDirectPushResult(
     ...(outcome?.blocked === true && {
       blocked: true,
       block_reason: outcome.blockReason,
-      sync_status: 'push_conflict' as const,
+      sync_status: outcome.syncStatus ?? ('push_conflict' as const),
     }),
     ...pushDetailsToWire(details),
   };

From ffd3eed9138c00f188281f9687add0a8cad06804 Mon Sep 17 00:00:00 2001
From: Christopher Tso <christso@gmail.com>
Date: Wed, 24 Jun 2026 16:26:08 +0200
Subject: [PATCH 2/4] test(results): cover no-force-push auto-merge sync and
 needs_human_merge

Replace the force-push/backup-conflict tests with auto-merge coverage over temp
local git remotes: disjoint diverged pushes produce a real merge commit and FF
the remote (no force, no backup ref); concurrent run-index appends union-merge;
overlay tag additions from both sides merge via the agentv-json driver; a genuine
overlay scalar conflict returns needs_human_merge with the remote unchanged; a
benign push race (remote advanced between fetch and push) retries and succeeds.
Assert the previous remote tip stays an ancestor and no agentv/backups ref is
ever created.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../core/test/evaluation/results-repo.test.ts | 422 ++++++++++++------
 1 file changed, 276 insertions(+), 146 deletions(-)

diff --git a/packages/core/test/evaluation/results-repo.test.ts b/packages/core/test/evaluation/results-repo.test.ts
index fd98efc4b..267573f48 100644
--- a/packages/core/test/evaluation/results-repo.test.ts
+++ b/packages/core/test/evaluation/results-repo.test.ts
@@ -1202,10 +1202,10 @@ describe('results repo write path', () => {
     );
   }, 20000);
 
-  it('blocks non-fast-forward direct result branch pushes by default', async () => {
+  it('auto-merges diverged direct result branch pushes without force or backup', async () => {
     const { remoteDir, seedDir } = initializeRemoteRepo(rootDir);
     const storageBranch = initializeRemoteStorageBranch(seedDir, DEFAULT_RESULTS_BRANCH);
-    const cloneDir = path.join(rootDir, 'results-clone-push-conflict-block');
+    const cloneDir = path.join(rootDir, 'results-clone-push-automerge');
     const fixture = await createStaleResultBranchPushFixture({
       rootDir,
       remoteDir,
@@ -1218,81 +1218,46 @@ describe('results repo write path', () => {
       config: { ...fixture.config, sync: { auto_push: true } },
       sourceDir: fixture.localSourceDir,
       destinationPath: fixture.localDestinationPath,
-      commitMessage: 'feat(results): blocked push conflict',
+      commitMessage: 'feat(results): auto-merge push conflict',
     });
 
-    expect(result).toMatchObject({
-      changed: false,
-      blocked: true,
-      sync_status: 'push_conflict',
-      push_conflict_policy: 'block',
-      target_branch: DEFAULT_RESULTS_BRANCH,
-      remote_commit: fixture.remoteAdvancedCommit,
-      previous_remote_commit: fixture.remoteAdvancedCommit,
-      lease_commit: fixture.remoteAdvancedCommit,
-    });
-    expect(result.local_commit).toMatch(/^[0-9a-f]{40}$/);
-    expect(result.block_reason).toContain('Results branch push conflict');
-    expect(git(`git --git-dir "${remoteDir}" rev-parse ${storageBranch}`, rootDir)).toBe(
-      fixture.remoteAdvancedCommit,
-    );
-    expect(
-      git(`git --git-dir "${remoteDir}" ls-tree -r --name-only ${storageBranch}`, rootDir),
-    ).not.toContain(`runs/${fixture.localDestinationPath}/benchmark.json`);
-  }, 30000);
+    expect(result.changed).toBe(true);
+    expect(result.blocked).toBeFalsy();
+    expect(result.backup_ref).toBeUndefined();
+    expect(result.force_pushed_commit).toBeUndefined();
 
-  it('backs up the remote result branch before force-pushing with an explicit policy', async () => {
-    const { remoteDir, seedDir } = initializeRemoteRepo(rootDir);
-    const storageBranch = initializeRemoteStorageBranch(seedDir, DEFAULT_RESULTS_BRANCH);
-    const cloneDir = path.join(rootDir, 'results-clone-push-conflict-backup');
-    const fixture = await createStaleResultBranchPushFixture({
+    const finalTip = git(`git --git-dir "${remoteDir}" rev-parse ${storageBranch}`, rootDir);
+    // The auto-merge produced a real merge commit (two parents), proving the
+    // remote and local histories were reconciled rather than force-overwritten.
+    const parents = git(
+      `git --git-dir "${remoteDir}" rev-list --parents -n 1 ${storageBranch}`,
       rootDir,
-      remoteDir,
-      seedDir,
-      cloneDir,
-      storageBranch,
-    });
-
-    const result = await directPushResultsWithDetails({
-      config: {
-        ...fixture.config,
-        sync: { auto_push: true, push_conflict_policy: 'backup_and_force_push' },
-      },
-      sourceDir: fixture.localSourceDir,
-      destinationPath: fixture.localDestinationPath,
-      commitMessage: 'feat(results): backup force push conflict',
-    });
+    ).split(/\s+/);
+    expect(parents).toHaveLength(3);
+    // The previous remote tip is an ancestor of the new tip: no history rewrite.
+    expect(() =>
+      git(
+        `git --git-dir "${remoteDir}" merge-base --is-ancestor ${fixture.remoteAdvancedCommit} ${finalTip}`,
+        rootDir,
+      ),
+    ).not.toThrow();
 
-    expect(result).toMatchObject({
-      changed: true,
-      push_conflict_policy: 'backup_and_force_push',
-      target_branch: DEFAULT_RESULTS_BRANCH,
-      backup_commit: fixture.remoteAdvancedCommit,
-      previous_remote_commit: fixture.remoteAdvancedCommit,
-      lease_commit: fixture.remoteAdvancedCommit,
-    });
-    expect(result.backup_ref).toMatch(
-      /^agentv\/backups\/\d{8}T\d{6}Z-agentv-results-v1-[0-9a-f]{7}$/,
-    );
-    expect(result.force_pushed_commit).toMatch(/^[0-9a-f]{40}$/);
-    expect(git(`git --git-dir "${remoteDir}" rev-parse ${storageBranch}`, rootDir)).toBe(
-      result.force_pushed_commit,
-    );
-    expect(git(`git --git-dir "${remoteDir}" rev-parse ${result.backup_ref}`, rootDir)).toBe(
-      fixture.remoteAdvancedCommit,
+    const remoteFiles = git(
+      `git --git-dir "${remoteDir}" ls-tree -r --name-only ${storageBranch}`,
+      rootDir,
     );
+    expect(remoteFiles).toContain(`runs/${fixture.localDestinationPath}/benchmark.json`);
+    expect(remoteFiles).toContain('runs/remote-only/2026-06-23T09-30-00-000Z/benchmark.json');
+    // No backup ref was ever created in the merge path.
     expect(
-      git(`git --git-dir "${remoteDir}" ls-tree -r --name-only ${storageBranch}`, rootDir),
-    ).toContain(`runs/${fixture.localDestinationPath}/benchmark.json`);
-    expect(
-      git(`git --git-dir "${remoteDir}" ls-tree -r --name-only ${result.backup_ref}`, rootDir),
-    ).toContain('runs/remote-only/2026-06-23T09-30-00-000Z/benchmark.json');
+      git(`git --git-dir "${remoteDir}" for-each-ref refs/heads/agentv/backups`, rootDir),
+    ).toBe('');
   }, 30000);
 
-  it('aborts backup-and-force-push when creating the backup ref fails', async () => {
+  it('deprecates backup_and_force_push by auto-merging instead of force pushing', async () => {
     const { remoteDir, seedDir } = initializeRemoteRepo(rootDir);
     const storageBranch = initializeRemoteStorageBranch(seedDir, DEFAULT_RESULTS_BRANCH);
-    const cloneDir = path.join(rootDir, 'results-clone-push-conflict-backup-fails');
+    const cloneDir = path.join(rootDir, 'results-clone-push-deprecated-policy');
     const fixture = await createStaleResultBranchPushFixture({
       rootDir,
       remoteDir,
@@ -1300,19 +1265,6 @@ describe('results repo write path', () => {
       cloneDir,
       storageBranch,
     });
-    const hookPath = path.join(remoteDir, 'hooks', 'pre-receive');
-    writeFileSync(
-      hookPath,
-      [
-        '#!/usr/bin/env sh',
-        'while read _old _new ref; do',
-        '  case "$ref" in',
-        '    refs/heads/agentv/backups/*) echo "reject backup ref" >&2; exit 1 ;;',
-        '  esac',
-        'done',
-      ].join('\n'),
-    );
-    chmodSync(hookPath, 0o755);
 
     const result = await directPushResultsWithDetails({
       config: {
@@ -1321,81 +1273,106 @@ describe('results repo write path', () => {
       },
       sourceDir: fixture.localSourceDir,
       destinationPath: fixture.localDestinationPath,
-      commitMessage: 'feat(results): backup creation fails',
+      commitMessage: 'feat(results): deprecated force policy auto-merges',
     });
 
-    expect(result).toMatchObject({
-      changed: false,
-      blocked: true,
-      sync_status: 'push_conflict',
-      backup_commit: fixture.remoteAdvancedCommit,
-      previous_remote_commit: fixture.remoteAdvancedCommit,
-    });
-    expect(result.block_reason).toContain('backup creation failed');
-    expect(result.backup_ref).toMatch(/^agentv\/backups\//);
-    expect(git(`git --git-dir "${remoteDir}" rev-parse ${storageBranch}`, rootDir)).toBe(
-      fixture.remoteAdvancedCommit,
-    );
-    expect(git(`git --git-dir "${remoteDir}" branch --list "${result.backup_ref}"`, rootDir)).toBe(
-      '',
+    expect(result.changed).toBe(true);
+    expect(result.blocked).toBeFalsy();
+    // The deprecated policy no longer force-pushes or backs anything up.
+    expect(result.backup_ref).toBeUndefined();
+    expect(result.force_pushed_commit).toBeUndefined();
+    expect(
+      git(`git --git-dir "${remoteDir}" for-each-ref refs/heads/agentv/backups`, rootDir),
+    ).toBe('');
+
+    const finalTip = git(`git --git-dir "${remoteDir}" rev-parse ${storageBranch}`, rootDir);
+    expect(() =>
+      git(
+        `git --git-dir "${remoteDir}" merge-base --is-ancestor ${fixture.remoteAdvancedCommit} ${finalTip}`,
+        rootDir,
+      ),
+    ).not.toThrow();
+    const remoteFiles = git(
+      `git --git-dir "${remoteDir}" ls-tree -r --name-only ${storageBranch}`,
+      rootDir,
     );
+    expect(remoteFiles).toContain(`runs/${fixture.localDestinationPath}/benchmark.json`);
+    expect(remoteFiles).toContain('runs/remote-only/2026-06-23T09-30-00-000Z/benchmark.json');
   }, 30000);
 
-  it('surfaces a stale lease when the target update is rejected after backup creation', async () => {
+  it('retries a benign push race without force', async () => {
     const { remoteDir, seedDir } = initializeRemoteRepo(rootDir);
     const storageBranch = initializeRemoteStorageBranch(seedDir, DEFAULT_RESULTS_BRANCH);
-    const cloneDir = path.join(rootDir, 'results-clone-push-conflict-lease');
-    const fixture = await createStaleResultBranchPushFixture({
-      rootDir,
-      remoteDir,
-      seedDir,
-      cloneDir,
-      storageBranch,
-    });
+    const cloneDir = path.join(rootDir, 'results-clone-push-race');
+    const config: ResultsConfig = {
+      repo: `file://${remoteDir}`,
+      path: cloneDir,
+      branch: storageBranch,
+      sync: { auto_push: true },
+    };
+    const baseTip = git(`git --git-dir "${remoteDir}" rev-parse ${storageBranch}`, rootDir);
 
+    // Simulate a concurrent writer: the first push attempt is rejected as a
+    // non-fast-forward AND the remote is advanced with a disjoint commit, so the
+    // loop must re-fetch, re-merge, and push again — all without force.
     const hookPath = path.join(remoteDir, 'hooks', 'pre-receive');
     writeFileSync(
       hookPath,
       [
         '#!/usr/bin/env sh',
-        'while read _old _new ref; do',
-        '  case "$ref" in',
-        `    refs/heads/${storageBranch}) echo "stale info" >&2; exit 1 ;;`,
-        '  esac',
-        'done',
+        'unset GIT_QUARANTINE_PATH GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES',
+        'export GIT_AUTHOR_NAME=Race',
+        'export GIT_AUTHOR_EMAIL=race@example.com',
+        'export GIT_COMMITTER_NAME=Race',
+        'export GIT_COMMITTER_EMAIL=race@example.com',
+        'read old new ref',
+        'marker="agentv-race-marker"',
+        'if [ ! -f "$marker" ]; then',
+        '  : > "$marker"',
+        `  base=$(git rev-parse "refs/heads/${storageBranch}")`,
+        '  blob=$(printf "concurrent\\n" | git hash-object -w --stdin)',
+        '  GIT_INDEX_FILE=./agentv-race-index git read-tree "$base"',
+        '  GIT_INDEX_FILE=./agentv-race-index git update-index --add --cacheinfo "100644,$blob,RACE.md"',
+        '  tree=$(GIT_INDEX_FILE=./agentv-race-index git write-tree)',
+        '  newcommit=$(printf "concurrent writer\\n" | git commit-tree "$tree" -p "$base")',
+        `  git update-ref "refs/heads/${storageBranch}" "$newcommit"`,
+        '  echo "non-fast-forward" >&2',
+        '  exit 1',
+        'fi',
+        'exit 0',
       ].join('\n'),
     );
     chmodSync(hookPath, 0o755);
 
+    const sourceDir = path.join(rootDir, 'race-local');
+    writeRunArtifacts(sourceDir, 'race-local', '2026-06-24T10:00:00.000Z');
     const result = await directPushResultsWithDetails({
-      config: {
-        ...fixture.config,
-        sync: { auto_push: true, push_conflict_policy: 'backup_and_force_push' },
-      },
-      sourceDir: fixture.localSourceDir,
-      destinationPath: fixture.localDestinationPath,
-      commitMessage: 'feat(results): stale lease fails',
+      config,
+      sourceDir,
+      destinationPath: path.join('race-local', '2026-06-24T10-00-00-000Z'),
+      commitMessage: 'feat(results): push race',
     });
 
-    expect(result).toMatchObject({
-      changed: false,
-      blocked: true,
-      sync_status: 'push_conflict',
-      backup_commit: fixture.remoteAdvancedCommit,
-      previous_remote_commit: fixture.remoteAdvancedCommit,
-      lease_commit: fixture.remoteAdvancedCommit,
-    });
-    expect(result.block_reason).toContain('force push lease failed');
-    expect(result.backup_ref).toMatch(/^agentv\/backups\//);
-    expect(git(`git --git-dir "${remoteDir}" rev-parse ${result.backup_ref}`, rootDir)).toBe(
-      fixture.remoteAdvancedCommit,
-    );
-    expect(git(`git --git-dir "${remoteDir}" rev-parse ${storageBranch}`, rootDir)).toBe(
-      fixture.remoteAdvancedCommit,
+    expect(result.changed).toBe(true);
+    expect(result.blocked).toBeFalsy();
+    expect(result.backup_ref).toBeUndefined();
+    expect(result.force_pushed_commit).toBeUndefined();
+
+    const finalTip = git(`git --git-dir "${remoteDir}" rev-parse ${storageBranch}`, rootDir);
+    // Both the original base and the concurrent writer's commit are ancestors of
+    // the final tip — nothing was overwritten.
+    expect(() =>
+      git(`git --git-dir "${remoteDir}" merge-base --is-ancestor ${baseTip} ${finalTip}`, rootDir),
+    ).not.toThrow();
+    const remoteFiles = git(
+      `git --git-dir "${remoteDir}" ls-tree -r --name-only ${storageBranch}`,
+      rootDir,
     );
+    expect(remoteFiles).toContain('RACE.md');
+    expect(remoteFiles).toContain('runs/race-local/2026-06-24T10-00-00-000Z/benchmark.json');
     expect(
-      git(`git --git-dir "${remoteDir}" ls-tree -r --name-only ${storageBranch}`, rootDir),
-    ).not.toContain(`runs/${fixture.localDestinationPath}/benchmark.json`);
+      git(`git --git-dir "${remoteDir}" for-each-ref refs/heads/agentv/backups`, rootDir),
+    ).toBe('');
   }, 30000);
 
   it('commits pushed runs into the configured clone with an AgentV-Run trailer', async () => {
@@ -1937,7 +1914,7 @@ describe('results repo write path', () => {
     );
   }, 20000);
 
-  it('blocks diverged committed histories as push conflicts with diff summary', async () => {
+  it('auto-merges diverged committed histories without force', async () => {
     const { remoteDir, seedDir } = initializeRemoteRepo(rootDir);
     const cloneDir = path.join(rootDir, 'results-clone');
     const config = createResultsConfig(remoteDir, cloneDir);
@@ -1953,18 +1930,169 @@ describe('results repo write path', () => {
     const remoteRunDir = path.join(seedDir, 'runs', 'remote-only', '2026-05-25T11-00-00-000Z');
     writeRunArtifacts(remoteRunDir, 'remote-only', '2026-05-25T11:00:00.000Z');
     git('git add runs && git commit --quiet -m "remote result"', seedDir);
+    const remoteBefore = git('git rev-parse HEAD', seedDir);
     git('git push --quiet origin main', seedDir);
 
     const status = await syncResultsRepoForProject(config);
 
-    expect(status.sync_status).toBe('push_conflict');
+    expect(status.sync_status).toBe('clean');
+    expect(status.blocked).toBe(false);
+    expect(status.push_performed).toBe(true);
+
+    const finalTip = git(`git --git-dir "${remoteDir}" rev-parse main`, rootDir);
+    const parents = git(`git --git-dir "${remoteDir}" rev-list --parents -n 1 main`, rootDir).split(
+      /\s+/,
+    );
+    expect(parents).toHaveLength(3);
+    expect(() =>
+      git(
+        `git --git-dir "${remoteDir}" merge-base --is-ancestor ${remoteBefore} ${finalTip}`,
+        rootDir,
+      ),
+    ).not.toThrow();
+    const remoteFiles = git(`git --git-dir "${remoteDir}" ls-tree -r --name-only main`, rootDir);
+    expect(remoteFiles).toContain('runs/local-only/2026-05-25T10-00-00-000Z/benchmark.json');
+    expect(remoteFiles).toContain('runs/remote-only/2026-05-25T11-00-00-000Z/benchmark.json');
+    expect(
+      git(`git --git-dir "${remoteDir}" for-each-ref refs/heads/agentv/backups`, rootDir),
+    ).toBe('');
+  }, 20000);
+
+  it('union-merges concurrent appends to the same run index without conflict', async () => {
+    const { remoteDir, seedDir } = initializeRemoteRepo(rootDir);
+    const cloneDir = path.join(rootDir, 'results-clone');
+    const config = createResultsConfig(remoteDir, cloneDir);
+    const indexRel = path.join('runs', 'shared', '2026-05-25T12-00-00-000Z', 'index.jsonl');
+
+    await ensureResultsRepoClone(config);
+    git('git config user.email "test@example.com"', cloneDir);
+    git('git config user.name "Test User"', cloneDir);
+
+    // Seed a shared run index on the remote and pull it into the clone.
+    const seedIndex = path.join(seedDir, indexRel);
+    mkdirSync(path.dirname(seedIndex), { recursive: true });
+    writeFileSync(seedIndex, '{"test_id":"base"}\n');
+    git('git add runs && git commit --quiet -m "seed shared index"', seedDir);
+    git('git push --quiet origin main', seedDir);
+    git('git pull --ff-only --quiet', cloneDir);
+
+    // Local appends one line; the remote concurrently appends a different line.
+    const localIndex = path.join(cloneDir, indexRel);
+    writeFileSync(localIndex, '{"test_id":"base"}\n{"test_id":"local"}\n');
+    git('git add runs && git commit --quiet -m "local index append"', cloneDir);
+    writeFileSync(seedIndex, '{"test_id":"base"}\n{"test_id":"remote"}\n');
+    git('git add runs && git commit --quiet -m "remote index append"', seedDir);
+    git('git push --quiet origin main', seedDir);
+
+    const status = await syncResultsRepoForProject(config);
+
+    expect(status.sync_status).toBe('clean');
+    expect(status.blocked).toBe(false);
+    expect(status.push_performed).toBe(true);
+
+    const merged = git(`git --git-dir "${remoteDir}" show main:${indexRel}`, rootDir);
+    expect(merged).toContain('"test_id":"local"');
+    expect(merged).toContain('"test_id":"remote"');
+  }, 20000);
+
+  it('auto-merges overlay tag additions from both sides via the agentv-json driver', async () => {
+    const { remoteDir, seedDir } = initializeRemoteRepo(rootDir);
+    const cloneDir = path.join(rootDir, 'results-clone');
+    const config = createResultsConfig(remoteDir, cloneDir);
+    const tagsRel = path.join(
+      'metadata',
+      'runs',
+      'overlay',
+      '2026-05-26T10-00-00-000Z',
+      'tags.json',
+    );
+    const writeTags = (repoDir: string, tags: string[], revision: string) => {
+      const tagPath = path.join(repoDir, tagsRel);
+      mkdirSync(path.dirname(tagPath), { recursive: true });
+      writeFileSync(
+        tagPath,
+        `${JSON.stringify({ tags, updated_at: '2026-05-26T10:00:00.000Z', tag_revision: revision }, null, 2)}\n`,
+      );
+    };
+
+    await ensureResultsRepoClone(config);
+    git('git config user.email "test@example.com"', cloneDir);
+    git('git config user.name "Test User"', cloneDir);
+
+    writeTags(seedDir, ['base'], 'r0');
+    git('git add metadata && git commit --quiet -m "seed tags"', seedDir);
+    git('git push --quiet origin main', seedDir);
+    git('git pull --ff-only --quiet', cloneDir);
+
+    writeTags(cloneDir, ['base', 'local-tag'], 'r1');
+    git('git add metadata && git commit --quiet -m "local tag add"', cloneDir);
+    writeTags(seedDir, ['base', 'remote-tag'], 'r2');
+    git('git add metadata && git commit --quiet -m "remote tag add"', seedDir);
+    git('git push --quiet origin main', seedDir);
+
+    const status = await syncResultsRepoForProject(config);
+
+    expect(status.sync_status).toBe('clean');
+    expect(status.blocked).toBe(false);
+    expect(status.push_performed).toBe(true);
+
+    const mergedTags = JSON.parse(
+      git(`git --git-dir "${remoteDir}" show main:${tagsRel}`, rootDir),
+    );
+    expect(mergedTags.tags).toContain('base');
+    expect(mergedTags.tags).toContain('local-tag');
+    expect(mergedTags.tags).toContain('remote-tag');
+    expect(
+      git(`git --git-dir "${remoteDir}" for-each-ref refs/heads/agentv/backups`, rootDir),
+    ).toBe('');
+  }, 20000);
+
+  it('returns needs_human_merge on a genuine overlay conflict without changing the remote', async () => {
+    const { remoteDir, seedDir } = initializeRemoteRepo(rootDir);
+    const cloneDir = path.join(rootDir, 'results-clone');
+    const config = createResultsConfig(remoteDir, cloneDir);
+    const tagsRel = path.join(
+      'metadata',
+      'runs',
+      'conflict',
+      '2026-05-27T10-00-00-000Z',
+      'tags.json',
+    );
+    const writeOverlay = (repoDir: string, rating: number) => {
+      const tagPath = path.join(repoDir, tagsRel);
+      mkdirSync(path.dirname(tagPath), { recursive: true });
+      writeFileSync(tagPath, `${JSON.stringify({ tags: ['keep'], rating }, null, 2)}\n`);
+    };
+
+    await ensureResultsRepoClone(config);
+    git('git config user.email "test@example.com"', cloneDir);
+    git('git config user.name "Test User"', cloneDir);
+
+    writeOverlay(seedDir, 1);
+    git('git add metadata && git commit --quiet -m "seed overlay"', seedDir);
+    git('git push --quiet origin main', seedDir);
+    git('git pull --ff-only --quiet', cloneDir);
+
+    // Both sides set a genuinely conflicting non-tag scalar field.
+    writeOverlay(cloneDir, 3);
+    git('git add metadata && git commit --quiet -m "local overlay scalar"', cloneDir);
+    writeOverlay(seedDir, 5);
+    git('git add metadata && git commit --quiet -m "remote overlay scalar"', seedDir);
+    const remoteBefore = git('git rev-parse HEAD', seedDir);
+    git('git push --quiet origin main', seedDir);
+
+    const status = await syncResultsRepoForProject(config);
+
+    expect(status.sync_status).toBe('needs_human_merge');
     expect(status.blocked).toBe(true);
-    expect(status.block_reason).toContain('Results branch push conflict');
-    expect(status.target_branch).toBe('main');
-    expect(status.remote_commit).toBe(git(`git --git-dir "${remoteDir}" rev-parse main`, rootDir));
-    expect(status.local_commit).toMatch(/^[0-9a-f]{40}$/);
-    expect(status.git_status).toContain('[ahead 1, behind 1]');
-    expect(status.git_diff_summary).toContain('benchmark.json');
+    expect(status.block_reason).not.toMatch(/force/i);
+    // The remote branch is untouched: no merge commit, no force, no backup.
+    expect(git(`git --git-dir "${remoteDir}" rev-parse main`, rootDir)).toBe(remoteBefore);
+    expect(
+      git(`git --git-dir "${remoteDir}" for-each-ref refs/heads/agentv/backups`, rootDir),
+    ).toBe('');
+    // The local checkout is clean (the failed merge was aborted).
+    expect(git('git status --porcelain', cloneDir)).toBe('');
   }, 20000);
 
   it('supersedes stale sync errors with the current conflicted status', async () => {
@@ -1978,17 +2106,17 @@ describe('results repo write path', () => {
       '2026-05-26T10-00-00-000Z',
       'tags.json',
     );
-    const writeTags = (repoDir: string, tags: string[]) => {
+    const writeTags = (repoDir: string, rating: number) => {
       const tagPath = path.join(repoDir, relativeMetadataPath);
       mkdirSync(path.dirname(tagPath), { recursive: true });
-      writeFileSync(tagPath, `${JSON.stringify({ tags }, null, 2)}\n`);
+      writeFileSync(tagPath, `${JSON.stringify({ tags: ['keep'], rating }, null, 2)}\n`);
     };
 
     await ensureResultsRepoClone(config);
     git('git config user.email "test@example.com"', cloneDir);
     git('git config user.name "Test User"', cloneDir);
 
-    writeTags(cloneDir, ['dirty']);
+    writeTags(cloneDir, 0);
     const dirtyStatus = await syncResultsRepoForProject(config);
     expect(dirtyStatus.sync_status).toBe('dirty');
     expect(dirtyStatus.block_reason).toContain('auto_push is disabled');
@@ -1996,14 +2124,16 @@ describe('results repo write path', () => {
     git('git reset --hard --quiet', cloneDir);
     git('git clean -fd --quiet metadata', cloneDir);
 
-    writeTags(seedDir, ['base']);
+    writeTags(seedDir, 1);
     git('git add metadata && git commit --quiet -m "seed tag metadata"', seedDir);
     git('git push --quiet origin main', seedDir);
     git('git pull --ff-only --quiet', cloneDir);
 
-    writeTags(cloneDir, ['local']);
+    // Both sides set a genuinely conflicting scalar so the agentv-json driver
+    // leaves the overlay conflicted instead of auto-merging it.
+    writeTags(cloneDir, 3);
     git('git add metadata && git commit --quiet -m "local tag metadata"', cloneDir);
-    writeTags(seedDir, ['remote']);
+    writeTags(seedDir, 5);
     git('git add metadata && git commit --quiet -m "remote tag metadata"', seedDir);
     git('git push --quiet origin main', seedDir);
     git('git fetch --quiet origin --prune', cloneDir);

From f53c65bb7230af51adfd3d38015fff0792ce6e6e Mon Sep 17 00:00:00 2001
From: Christopher Tso <christso@gmail.com>
Date: Wed, 24 Jun 2026 16:26:20 +0200
Subject: [PATCH 3/4] feat(dashboard): surface needs_human_merge without
 force-push guidance

Add the needs_human_merge sync state to the dashboard status types and view, and
stop recommending backup_and_force_push in push-conflict next actions now that
results sync auto-merges and never force-pushes. The needs_human_merge view points
users to a GitHub pull request instead.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../src/lib/project-sync-status.test.ts       | 17 +++++++++++++++++
 apps/dashboard/src/lib/project-sync-status.ts | 19 ++++++++++++++++---
 apps/dashboard/src/lib/types.ts               |  1 +
 3 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/apps/dashboard/src/lib/project-sync-status.test.ts b/apps/dashboard/src/lib/project-sync-status.test.ts
index 36b601758..98c0edeff 100644
--- a/apps/dashboard/src/lib/project-sync-status.test.ts
+++ b/apps/dashboard/src/lib/project-sync-status.test.ts
@@ -102,6 +102,23 @@ describe('getProjectSyncView', () => {
       canSync: false,
     });
   });
+
+  it('surfaces a needs-human-merge conflict without suggesting force push', () => {
+    const view = getProjectSyncView({
+      configured: true,
+      available: true,
+      sync_status: 'needs_human_merge',
+      block_reason: 'Results branch agentv/results/v1 diverged and could not be auto-merged',
+    });
+    expect(view).toMatchObject({
+      state: 'needs_human_merge',
+      label: 'Needs human merge',
+      tone: 'danger',
+      canSync: false,
+    });
+    expect(view.nextAction).not.toMatch(/force/i);
+    expect(view.nextAction).toMatch(/pull request/i);
+  });
 });
 
 describe('buildProjectSyncFeedback', () => {
diff --git a/apps/dashboard/src/lib/project-sync-status.ts b/apps/dashboard/src/lib/project-sync-status.ts
index 6920ae6a0..4e3444b98 100644
--- a/apps/dashboard/src/lib/project-sync-status.ts
+++ b/apps/dashboard/src/lib/project-sync-status.ts
@@ -9,6 +9,7 @@ export type ProjectSyncState =
   | 'dirty'
   | 'conflicted'
   | 'push_conflict'
+  | 'needs_human_merge'
   | 'syncing';
 
 export type ProjectSyncTone = 'neutral' | 'good' | 'info' | 'warn' | 'danger';
@@ -122,6 +123,20 @@ export function getProjectSyncView(
   }
 
   const state = status.sync_status ?? 'clean';
+  if (state === 'needs_human_merge') {
+    return {
+      state: 'needs_human_merge',
+      label: 'Needs human merge',
+      actionLabel: 'Sync Project',
+      tone: 'danger',
+      summary:
+        status.block_reason ??
+        'The results branch diverged and a genuine content conflict could not be auto-merged.',
+      nextAction:
+        'The remote branch is unchanged and no history was rewritten. Resolve the conflict with a GitHub pull request, then sync again.',
+      canSync: false,
+    };
+  }
   if (state === 'push_conflict') {
     return {
       state: 'push_conflict',
@@ -132,9 +147,7 @@ export function getProjectSyncView(
         status.block_reason ??
         'The remote results branch changed before local results could be pushed.',
       nextAction:
-        status.push_conflict_policy === 'backup_and_force_push'
-          ? 'Sync stopped before changing the results branch. Refresh status, then retry if this server should replace the remote branch.'
-          : 'Sync stopped before changing the results branch. Opt in to backup_and_force_push only if this server should replace the remote branch.',
+        'Sync stopped before changing the results branch. Refresh status, then retry — results sync auto-merges concurrent writes and never force-pushes.',
       canSync: false,
     };
   }
diff --git a/apps/dashboard/src/lib/types.ts b/apps/dashboard/src/lib/types.ts
index 3c03e1ca0..09c7f54cb 100644
--- a/apps/dashboard/src/lib/types.ts
+++ b/apps/dashboard/src/lib/types.ts
@@ -470,6 +470,7 @@ export interface RemoteStatusResponse {
     | 'dirty'
     | 'conflicted'
     | 'push_conflict'
+    | 'needs_human_merge'
     | 'syncing';
   branch?: string;
   upstream?: string;

From d904ca266a674832d816d7bd14acecfdaecbf20c Mon Sep 17 00:00:00 2001
From: Christopher Tso <christso@gmail.com>
Date: Thu, 25 Jun 2026 01:46:53 +0200
Subject: [PATCH 4/4] fix(results): drop tag_revision on overlay auto-merge to
 preserve concurrency guard

The agentv-json driver carried tag_revision forward as max() of the two
sides' hashes. Because tag_revision is a content-derived optimistic-
concurrency token, a stale client holding the surviving hash could pass
assertExpectedTagRevision and silently overwrite the merged tag union.
Drop tag_revision during a real merge so the reader recomputes a token
matching the merged content; updated_at (display-only) still regenerates.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 packages/core/src/evaluation/results-repo.ts  | 20 ++++++++++++++-----
 .../core/test/evaluation/results-repo.test.ts |  5 +++++
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/packages/core/src/evaluation/results-repo.ts b/packages/core/src/evaluation/results-repo.ts
index 25ea43d79..eba76ace3 100644
--- a/packages/core/src/evaluation/results-repo.ts
+++ b/packages/core/src/evaluation/results-repo.ts
@@ -94,10 +94,13 @@ const RESULTS_JSON_MERGE_DRIVER_SCRIPT = `#!/usr/bin/env node
 //
 // Performs a 3-way merge of AgentV's editable JSON overlay files (run tags /
 // feedback). Tag lists merge as a 3-way set so concurrent add/remove are
-// commutative; bookkeeping scalars that always differ between writers
-// (updated_at, tag_revision) are regenerated to the larger value instead of
-// conflicting. Any other genuinely diverging scalar exits non-zero, leaving the
-// file conflicted so the caller can route it to a human GitHub merge.
+// commutative; display-only bookkeeping scalars that always differ between
+// writers (updated_at) are regenerated to the larger value instead of
+// conflicting. Content-derived concurrency tokens (tag_revision) are dropped on
+// merge so the reader recomputes a token matching the merged content rather than
+// carrying a stale token that could bypass optimistic-concurrency checks. Any
+// other genuinely diverging scalar exits non-zero, leaving the file conflicted
+// so the caller can route it to a human GitHub merge.
 //
 // Invoked by git as: node json-merge-driver.mjs %O %A %B %P
 //   %O ancestor, %A current (overwritten with the result), %B other, %P path.
@@ -106,7 +109,13 @@ import { readFileSync, writeFileSync } from 'node:fs';
 const [, , ancestorFile, currentFile, otherFile] = process.argv;
 const CONFLICT = Symbol('conflict');
 // Scalars that legitimately differ on every write and carry no merge meaning.
-const REGENERABLE_SCALARS = new Set(['updated_at', 'tag_revision']);
+const REGENERABLE_SCALARS = new Set(['updated_at']);
+// Content-derived tokens (a hash of {tags, updated_at}) that guard optimistic
+// concurrency. Carrying either side's pre-merge token forward would let a stale
+// client whose token happens to match bypass the concurrency check and silently
+// overwrite the merged set, so we drop them and let the reader recompute a token
+// that matches the merged content.
+const DROP_ON_MERGE = new Set(['tag_revision']);
 
 function readJson(file) {
   try {
@@ -160,6 +169,7 @@ function merge3(base, a, b, key) {
     ]);
     const out = {};
     for (const childKey of keys) {
+      if (DROP_ON_MERGE.has(childKey)) continue;
       const merged = merge3(
         isPlainObject(base) ? base[childKey] : undefined,
         a[childKey],
diff --git a/packages/core/test/evaluation/results-repo.test.ts b/packages/core/test/evaluation/results-repo.test.ts
index 267573f48..38dc2b6de 100644
--- a/packages/core/test/evaluation/results-repo.test.ts
+++ b/packages/core/test/evaluation/results-repo.test.ts
@@ -2042,6 +2042,11 @@ describe('results repo write path', () => {
     expect(mergedTags.tags).toContain('base');
     expect(mergedTags.tags).toContain('local-tag');
     expect(mergedTags.tags).toContain('remote-tag');
+    // The content-derived concurrency token must NOT survive a real set merge as
+    // either side's pre-merge value; otherwise a stale client holding that token
+    // would bypass the optimistic-concurrency check and overwrite the union.
+    expect(mergedTags.tag_revision).not.toBe('r1');
+    expect(mergedTags.tag_revision).not.toBe('r2');
     expect(
       git(`git --git-dir "${remoteDir}" for-each-ref refs/heads/agentv/backups`, rootDir),
     ).toBe('');