I Watched an Agent Try to Fix a File It Had Already Fixed — Stale Shallow Clones and Refreshing Before You Decide

Why a Shallow Persistent Clone Ages in Silence

Reusing a --depth 1 shallow clone for speed has a clear upside. It is far faster than a full clone every run, and light on disk. My own clone, built without node_modules, lands around 30MB, so the urge to reuse it is natural.

The problem is that a shallow clone is easy to mistake for current. There are several routes by which it goes old.

1. Another session or machine pushed first. When you distribute automation, a single repository has multiple writers. The remote moves while you sleep.
2. The pull did not run, or was swallowed. If a rebase conflict or a brief network hiccup leaves pull half-finished, downstream steps may keep running as if nothing happened.
3. A shallow history makes pull behavior hard to read. With almost no history locally, --depth 1 makes rebases misbehave more often than you would expect.

None of these throws a loud error. That is why it "ages in silence." And in unattended operation, there is no human present to doubt that silence.

See Staleness as a Number — Compare Local HEAD to Remote HEAD

The heart of the fix is to stop asking "did pull succeed?" and instead produce a number: "how many commits behind the remote is the tree I am reading right now?" Because git ls-remote fetches only a reference over the network, you can check the remote tip without touching your working tree.

Here is the naive version I wanted to get away from.

# Before: trust that pull succeeded, then proceed to decide
cd "$WORK"
git pull --rebase origin main   # may not halt downstream even if it fails
# now read content/ and conclude "not there yet" -> wrong call on an old tree

And here is the version that measures the gap before deciding. It reads the remote tip first and compares.

# After: before deciding, report the gap as a commit count
cd "$WORK"
LOCAL=$(git rev-parse HEAD)
REMOTE=$(git ls-remote origin -h refs/heads/main | cut -f1)
 
if [ "$LOCAL" != "$REMOTE" ]; then
  # count how far behind (a shallow history may not have enough to count)
  git fetch --depth 50 origin main 2>/dev/null
  BEHIND=$(git rev-list --count "HEAD..$REMOTE" 2>/dev/null || echo "unknown")
  echo "stale: local=$LOCAL remote=$REMOTE behind=$BEHIND"
fi

The key point is that ls-remote changes nothing in the working tree. You measure the freshness of a read without contaminating the read you are about to judge from. The moment LOCAL != REMOTE appears, you know mechanically that the current tree is no longer trustworthy as a basis for a decision.

Re-clone or Catch Up — Where the Decision Forks

Once you know the gap, the next question is how to close it. This is not one-size-fits-all; choose based on what the read drives.

The rule I settled on is simple. If the read decides what to do next, re-clone without hesitation. For reads that only display or tally — things you can correct later if wrong — catching up is enough. Be strict about freshness only for reads that drive decisions. That keeps the re-clone count low while pulling the wrong-call seedlings out by the root.

You may also run into side issues, such as a /tmp shallow clone you cannot delete because it is owned by another user. When that happens, do not cling to it; cloning fresh into a different, writable path is the fastest move in the end. One re-clone resolves the freshness and the ownership problem together.

Idempotency Is What Stops Duplicate Work

Detecting freshness is only half of the machinery that prevents duplicate work. The other half is making generation itself idempotent — that is, "if it is already done, do nothing," confirmed against reality right before generating.

# before generating, confirm against reality whether the artifact exists
TARGET="content/articles/en/${CAT}/${SLUG}.mdx"
if [ -f "$TARGET" ]; then
  echo "skip: $SLUG already exists (avoid double generation)"
  exit 0
fi
# from here on, "truly not there yet" is guaranteed

It is modest, but it also stops the leaks that slip past freshness detection. Freshness detection prevents "starting to think on an old foundation"; the idempotency check prevents "building the same artifact twice." Their roles differ, so you only feel safe with both. Even my double-fix would have stopped at the last step — old tree or not — had this existence check sat in front of generation.

Wire It Into Operations — A Verdict Function and a Log

Finally, fold all of this into a single verdict. Because it runs unattended, always log the basis for the decision. Letting a human trace "why did it re-clone?" afterward is what makes unattended operation feel safe.

# refresh_if_stale: call before a decision. returns true when stale.
refresh_if_stale() {
  local work="$1" remote_url="$2"
  cd "$work" || return 1
  local local_sha remote_sha
  local_sha=$(git rev-parse HEAD)
  remote_sha=$(git ls-remote "$remote_url" -h refs/heads/main | cut -f1)
  if [ "$local_sha" = "$remote_sha" ]; then
    echo "[fresh] $(TZ=Asia/Tokyo date +%H:%M) local==remote ${local_sha:0:7}"
    return 1
  fi
  echo "[stale] local=${local_sha:0:7} remote=${remote_sha:0:7} -> re-clone"
  return 0
}
 
# caller
if refresh_if_stale "$WORK" "$REMOTE_URL"; then
  # re-clone only before a read that drives a decision
  rm -rf "$WORK" && git clone --depth 1 "$REMOTE_URL" "$WORK"
fi

I spell out TZ=Asia/Tokyo to avoid an accident where the log timestamp drifts to UTC and overwrites the previous day's record. That, too, is something unattended operation taught me the hard way, and I have added it ever since. The verdict is only a few lines, but the design intent — deciding in advance where to doubt freshness — is what quietly heads off duplicate work and wrong calls.

As a next step, pick one of your running unattended jobs and write down where the "reads that drive decisions" are. Wrap just those in refresh_if_stale. Usually a single function closes off the whole path to a quiet, wrong decision. Thank you for reading.