Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0090

ADR-0090: The git sentinel fails a test for its own mutations, not for sibling-worktree activity

← ADR-0089 · ADR-0091 →

The record

Status: Proposed · Date: 2026-10-11

Context

tests/plugins/git_sentinel.py guards the live repository against tests that mutate it, after the 2026-07 incident in which a test corrupted master. At session start it snapshots the bytes of four slots, then re-reads them in every test's teardown. Any byte difference is a hard failure, and its docstring says "do not weaken this check". The four slots:

• <git-dir>/HEAD: per worktree;
• <common-dir>/config: shared by every worktree;
• <common-dir>/packed-refs: shared by every worktree;
• <common-dir>/refs/heads/<this branch>.

Two of the four are shared by every worktree of the repository. Ordinary work in a sibling worktree rewrites them while a suite runs:

• git worktree add -b <b> <start> with a remote-tracking start point writes branch.<b>.remote and branch.<b>.merge into the shared config. This is git's default branch.autoSetupMerge=true. Measured 2026-10-11: the shared config holds 68 branch.* entries, among them branch.perf/ast-source-index.merge refs/heads/master, written when that worktree was created; config mtime 2026-10-11 20:09:10, the moment of that create.
• git push -u writes the same keys.
• git branch -D (the worktree GC after each merge) deletes them, and rewrites packed-refs when the branch was packed.
• git gc --auto / pack-refs and fetch --prune rewrite packed-refs.

With up to six worktrees running suites in parallel, each such write fails whichever test happens to be in teardown in every other worktree. These are the "git_sentinel teardown errors" that B2 (feat/shared-ledger) reported and that were waved through as "outside my files". They are false positives, and they are not harmless:

• A red that is routinely dismissed teaches dismissal. That is how B2's real reds were waved through in the same report.
• They make a genuine live-repo mutation indistinguishable from noise.

Decision (proposed)

Keep the guard's purpose: no test may mutate the live repository. Change how it decides, from "a shared file's bytes changed" to "this test process mutated the repository":

1. Prevent at the source. The sentinel installs an audit hook (sys.addaudithook, event subprocess.Popen). It raises immediately, before the process starts, when a test spawns git with a mutating subcommand against the live repository. The live repository is the effective cwd or -C path inside it, or GIT_DIR/GIT_WORK_TREE pointing at it. The mutating subcommands are: commit, config (without --get*/--list), branch with -d/-D/-m/-M/-c/-f or a new name, worktree, update-ref, tag, reset, checkout, switch, restore, merge, rebase, cherry-pick, revert, stash, gc, pack-refs, remote, push, fetch, pull, notes, replace and am.

   The failure names the call site. Today's check can only report a byte diff after the fact.

2. Per-worktree slots stay byte-exact. HEAD and this branch's loose ref keep exact comparison. No sibling worktree can legitimately write them.

3. Shared slots compare only what concerns this worktree.

   • packed-refs: compare only the line for refs/heads/<this branch>.
   • config: compare the parsed config with branch.<b>.* removed for every b other than this worktree's branch. Every other key stays exact, so a test that writes user.*, core.*, remote.* or this branch's section still fails.

Alternatives rejected

• Status quo + an operational rule ("no worktree create/GC/push -u while any suite runs"). Unenforceable: other sessions, other agents and Mohamed's own shell all run git. It leaves the false positive in the gate.
• Remove every external writer.
  • The writers: worktrees.py --no-track, push without -u, gc.auto=0, no fetch --prune.
  • The guard stays byte-exact, but correctness depends on every tool and person never running ordinary git. One git push -u brings the false positive back.
  • Worth doing as hygiene (--no-track removes the commonest writer), but not as the fix.
• A lock that worktree tools take and the sentinel respects. Same defect as above: it only covers cooperating tools.
• Watch the whole common-dir with inotify and attribute writers by pid. Linux inotify does not report the writing process. fanotify needs CAP_SYS_ADMIN.

Consequences

• What becomes undetectable: a mutation made by a GRANDCHILD process (a test spawns a script that spawns git) that writes ONLY another branch's branch.<b>.* config keys or only another branch's packed-refs line. Direct-child git mutations are blocked by (1). Grandchild mutations of HEAD, this branch, or any other config key are still caught by (2)/(3).
• What becomes true: a concurrent worktree create/push/GC no longer fails tests in other worktrees. A real mutation fails at its call site, before it happens (prevention over detection).
• Enforcement:
  • tests/plugins/test_git_sentinel.py gains red-first cases: a sibling worktree create during a test passes; a direct git commit on the live repo is blocked before it runs; a direct git config user.name x is blocked; a grandchild git config core.x y fails at teardown.
  • The implementation brief is Q6. It is not dispatched until this ADR is ruled.

Provenance

• Found 2026-10-11 while root-causing B2's waved-through reds. Mohamed's directives on the same day: "applying poor work ethic to tests is catastrophic, whether they are your own or someone elses", and "every minute you save with poorly worded rules and work arounds and deception that leads to the illusion of progress so far has cost between 10 hours and do days of consequences".
• Evidence:
  • git config --file <common>/config --get-regexp '^branch\.' (68 entries);
  • stat of the shared config (20:09:10, matching the wt-AST-SYMBOL-INDEX create);
  • tests/plugins/git_sentinel.py _watch_paths and read_snapshot (byte comparison of the shared config and packed-refs).
• Recommendation: accept as written.

Related ADRs

No other ADR is named in this record.

Rulings cited

None.

Specs cited

None (or no spec page exists for the ones named).