Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(git): refuse every move of local main to a commit no remote has (#585)

Ruben Lütkef91708cbac36
diff --git a/.githooks/reference-transaction b/.githooks/reference-transaction
new file mode 100755
index 0000000000..d5650025ba
--- /dev/null
+++ b/.githooks/reference-transaction
@@ -0,0 +1,48 @@
+#!/bin/sh
+# reference-transaction: local main only moves to a commit a remote main has.
+#
+# Local main mirrors the remote. The pre-commit BRANCH gate stops a commit on
+# it, but not the other ways a ref moves: `git update-ref`, `git commit
+# --no-verify`, a cherry-pick, a rebase, `git branch -f`. Each of those leaves
+# local main on a commit that exists on one machine, and since the merge queue
+# squash-merges, local and remote main then stop sharing history.
+#
+# git runs this hook for every ref transaction and passes the state as $1; the
+# updates arrive on stdin, one per line:
+# <old-value> <new-value> <ref-name>
+# Only the "prepared" state can still refuse, so every other state returns at
+# once, and so does a transaction that does not touch refs/heads/main.
+#
+# Allowed: a new value that some remote-tracking main already contains
+# (`git pull --ff-only`, `git reset --hard origin/main`), deleting the branch,
+# a repository with no remote main to mirror, and CI runners.
+# Fails OPEN when git cannot answer.
+#
+# This hook is VERSIONED in .githooks/; git runs it via core.hooksPath=.githooks
+# (set by scripts/ci/install_git_hooks.py). It never sets that itself.
+
+[ "$1" = "prepared" ] || exit 0
+[ "$GITHUB_ACTIONS" = "true" ] && exit 0
+
+while read -r old new ref; do
+ [ "$ref" = "refs/heads/main" ] || continue
+ # All zeros: the branch is being deleted, nothing can diverge.
+ case "$new" in *[!0]*) ;; *) continue ;; esac
+
+ remotes=$(git for-each-ref --format='%(refname)' 'refs/remotes/*/main' 2>/dev/null) || continue
+ [ -n "$remotes" ] || continue
+ holders=$(git for-each-ref --format='%(refname)' --contains "$new" \
+ 'refs/remotes/*/main' 2>/dev/null) || continue
+ [ -n "$holders" ] && continue
+
+ echo "" >&2
+ echo "reference-transaction BLOCKED: main may only move to a commit a remote main has." >&2
+ echo " $new is on no remote main, so local main would diverge from it." >&2
+ echo " Put the change on a feature branch in a worktree of your own:" >&2
+ echo " git worktree add -b <agent>/<topic> <path> origin/main" >&2
+ echo " and land it with: python scripts/agent_land.py" >&2
+ echo " To follow the remote: git pull --ff-only" >&2
+ exit 1
+done
+
+exit 0
diff --git a/AGENTS.md b/AGENTS.md
index f3af2f2ed9..dcfba9b6e9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,7 +28,8 @@ These cost real bugs. Nothing catches them but you.
`pip install -e` from a linked worktree: that pin is the user's desktop app,
and their next restart boots your branch with an empty `data/`. (BUG-219)
- **`main` takes no local commits.** Local `main` mirrors `origin/main` and
- moves only by `git pull --ff-only`; the commit hook refuses a commit on it.
+ moves only by `git pull --ff-only`; the hooks refuse a commit on it and any
+ other move (`update-ref`, cherry-pick, rebase) to a commit no remote has.
Every change lives on a feature branch in a worktree of your own:
`git worktree add -b <agent>/<topic> <path> origin/main`, one topic per
branch. A commit on local `main` exists on one machine, and the squash-merging
diff --git a/docs/ci-pipeline.md b/docs/ci-pipeline.md
index 745e3f0054..ca35e59b6b 100644
--- a/docs/ci-pipeline.md
+++ b/docs/ci-pipeline.md
@@ -258,11 +258,15 @@ python scripts/agent_land.py # feature branch -> PR labelled auto-mer
python scripts/agent_land.py --direct # admin only: fast-forward main itself
```
-Local `main` is a mirror of `origin/main`: the commit hook
-(`scripts/ci/check_commit_branch.py`) refuses a commit on it, and the script
-refuses to land from it. Work starts on a branch cut from `origin/main`
-(`git worktree add -b <agent>/<topic> <path> origin/main`) and the main
-checkout follows with `git pull --ff-only` once the pull request has merged.
+Local `main` is a mirror of `origin/main`. The commit hook
+(`scripts/ci/check_commit_branch.py`) refuses a commit on it, the
+`reference-transaction` hook refuses every other move of it (`git update-ref`,
+a cherry-pick, a rebase, `--no-verify`) to a commit no remote `main` contains,
+and the script refuses to land from it. Work starts on a branch cut from
+`origin/main` (`git worktree add -b <agent>/<topic> <path> origin/main`) and
+the main checkout follows with `git pull --ff-only` once the pull request has
+merged. Hooks come from the checkout a command runs in, so a worktree cut
+before a hook existed does not have it until it is rebased.
It rebases onto the latest main with the same conflict engine, runs the
static gates, runs the tests the diff can reach, pushes, and asks GitHub to
diff --git a/tests/unit/ci/test_reference_transaction_hook.py b/tests/unit/ci/test_reference_transaction_hook.py
new file mode 100644
index 0000000000..ceda24ad50
--- /dev/null
+++ b/tests/unit/ci/test_reference_transaction_hook.py
@@ -0,0 +1,133 @@
+"""Local ``main`` only moves to a commit a remote ``main`` already has."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+HOOK = Path(__file__).resolve().parents[3] / ".githooks" / "reference-transaction"
+
+# git runs hooks through a POSIX shell; without one the hook cannot be exercised.
+pytestmark = pytest.mark.skipif(shutil.which("git") is None, reason="git is not installed")
+
+
+def _git(repo: Path, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+ return subprocess.run(
+ ["git", "-C", str(repo), *args],
+ check=check,
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ )
+
+
+def _commit(repo: Path, message: str) -> str:
+ _git(repo, "commit", "-q", "--allow-empty", "-m", message)
+ return _git(repo, "rev-parse", "HEAD").stdout.strip()
+
+
+def _configure(repo: Path) -> None:
+ _git(repo, "config", "user.email", "[email protected]")
+ _git(repo, "config", "user.name", "Test")
+ _git(repo, "config", "commit.gpgsign", "false")
+
+
+def clone(tmp_path: Path, monkeypatch) -> Path:
+ """A clone whose ``origin/main`` is one commit ahead of nothing local."""
+ monkeypatch.delenv("GITHUB_ACTIONS", raising=False)
+ remote = tmp_path / "remote"
+ remote.mkdir()
+ _git(remote, "init", "-q", "-b", "main")
+ _configure(remote)
+ _commit(remote, "chore: seed")
+
+ repo = tmp_path / "clone"
+ subprocess.run(["git", "clone", "-q", str(remote), str(repo)], check=True, capture_output=True)
+ _configure(repo)
+ hooks = tmp_path / "hooks"
+ hooks.mkdir()
+ target = hooks / "reference-transaction"
+ target.write_bytes(HOOK.read_bytes())
+ target.chmod(0o755)
+ _git(repo, "config", "core.hooksPath", str(hooks))
+ return repo
+
+
+def _remote_advances(clone: Path) -> str:
+ remote = clone.parent / "remote"
+ tip = _commit(remote, "feat: landed upstream")
+ _git(clone, "fetch", "-q", "origin")
+ return tip
+
+
+def test_commit_on_main_is_refused(clone):
+ before = _git(clone, "rev-parse", "main").stdout.strip()
+
+ result = _git(clone, "commit", "--allow-empty", "-m", "feat: local only", check=False)
+
+ assert result.returncode != 0
+ assert "reference-transaction BLOCKED" in result.stderr
+ assert _git(clone, "rev-parse", "main").stdout.strip() == before
+
+
+def test_update_ref_to_a_local_commit_is_refused(clone):
+ _git(clone, "switch", "-q", "-c", "claude/topic")
+ local = _commit(clone, "feat: on a branch")
+ before = _git(clone, "rev-parse", "main").stdout.strip()
+
+ result = _git(clone, "update-ref", "refs/heads/main", local, check=False)
+
+ assert result.returncode != 0
+ assert _git(clone, "rev-parse", "main").stdout.strip() == before
+
+
+def test_fast_forward_to_the_remote_is_allowed(clone):
+ tip = _remote_advances(clone)
+
+ _git(clone, "merge", "-q", "--ff-only", "origin/main")
+
+ assert _git(clone, "rev-parse", "main").stdout.strip() == tip
+
+
+def test_reset_to_the_remote_is_allowed(clone):
+ tip = _remote_advances(clone)
+
+ _git(clone, "reset", "-q", "--hard", "origin/main")
+
+ assert _git(clone, "rev-parse", "main").stdout.strip() == tip
+
+
+def test_feature_branches_move_freely(clone):
+ _git(clone, "switch", "-q", "-c", "claude/topic")
+
+ tip = _commit(clone, "feat: on a branch")
+
+ assert _git(clone, "rev-parse", "claude/topic").stdout.strip() == tip
+
+
+def test_deleting_main_is_allowed(clone):
+ _git(clone, "switch", "-q", "-c", "claude/topic")
+
+ _git(clone, "branch", "-D", "main")
+
+ assert _git(clone, "rev-parse", "--verify", "-q", "refs/heads/main", check=False).returncode
+
+
+def test_repository_without_a_remote_main_is_left_alone(clone):
+ _git(clone, "remote", "remove", "origin")
+
+ tip = _commit(clone, "feat: nothing to mirror")
+
+ assert _git(clone, "rev-parse", "main").stdout.strip() == tip
+
+
+def test_ci_runner_is_left_alone(clone, monkeypatch):
+ monkeypatch.setenv("GITHUB_ACTIONS", "true")
+
+ tip = _commit(clone, "chore: written by a workflow")
+
+ assert _git(clone, "rev-parse", "main").stdout.strip() == tip