---
title: Git history missing (the store-loss alert)
---
# Git history missing (the store-loss alert)

## What it is

Every project the app manages keeps its whole git history in one hidden folder, `.git`. That
folder holds the only copy of every branch that has not been pushed anywhere, so if it is deleted,
emptied or replaced by a fresh empty history, work that exists nowhere else is at risk.

The app watches for that. When a project's history goes missing, it raises one alert in your inbox
within about a minute, and it stops its own git work on that project so nothing gets written into a
broken or empty history while it is being put back.

## Where to find it

The alert appears in the Inbox, titled "A project's git history is missing — the app stopped its own
git writes". There is nothing to switch on: the watch runs in the background for every managed
project.

## How it behaves

- **What counts as missing.** The history folder is gone, emptied, or replaced by a new history that
  does not match the one the app knew (its main branch gone, its stored history gone, or the
  worktrees still pointing at it no longer known to it). Removing the online copy's address is not a
  loss. A project
  the app has never seen healthy is not treated as missing, so a brand-new or placeholder folder
  never raises the alert — and neither does a project whose whole folder was deleted, moved or is on
  a drive that is unplugged, because nothing is left there to protect.
- **One alert, not a flood.** The alert is raised after two failed checks in a row, about thirty
  seconds apart, so a single slow disk read cannot raise it. It is not silenced by the usual alert
  switches or an inbox rule, or held back to be batched, because it protects your data. It stays one card while the
  history is missing: dismiss it, or start a session from it, and it comes back until the history
  is whole again.
- **What stops.** The auto-lander lands nothing, worktree cleanup and retire jobs wait, and new
  worktrees are refused with a clear "history missing" answer instead of being created. A session
  that would work in its own worktree is not started, or resumed, in your project folder instead; it
  waits too, except the recovery session started from the alert.
- **How to fix it.** Start a session from the alert's button. That session runs the repository's
  restore command when it has one, and otherwise tells you plainly that the restore tool is not
  installed yet — it never tries to rebuild the history by hand. While a restore is in progress, the
  app keeps everything paused, and the same alert says a restore is running instead of offering a
  second one; if the restore ends with the history still missing, the alert switches back.
- **What it is restored FROM.** In the background, every ten minutes, the app keeps a copy of each
  project's history on a **different drive** — its branches, its worktree links, and every object
  that exists only on this computer. The copy only ever ADDS: nothing is ever removed from it, so a
  history that is destroyed can never overwrite the copy of itself. That is why a recovered project
  can also get back a branch that had already been retired before the loss. Restoring puts the
  history back as a real folder where the app expects it — never a shortcut to somewhere else — and
  finishes by fetching the file contents the sessions need, so they can save their work again
  straight away instead of one failing save at a time.
- **Resuming.** Once the history reads healthy on three checks in a row, and no restore is still
  running, everything resumes by itself. There is nothing to turn back on. A replacement history
  never counts as healthy on its own: the app waits until the history it knew is back, or a restore
  has run.

## For agents

- The watch is `startGitStoreLossWatch` in src/main/services/worktree/git-store-loss-watch.ts; the
  health reader is src/main/services/worktree/git-store-health.ts. The watch's state is kept in
  ~/.amc/git-store-watch.json.
- A restore in progress is marked by a `.git-restore-in-progress` file beside the project's `.git`.
  While it exists, every writer stays refused.
- A request for a new worktree through the control server answers `503` with the `store-lost` code
  for a project whose known history is missing.
- The backstop is `scripts/lib/git-store-backstop.mjs`, run every ten minutes by the
  `AMC-Git-Store-Backstop` row in `scripts/ops/ops-tasks/`. It reads the WATCH's verdict from
  `~/.amc/git-store-watch.json` and copies a store only when the watch reads it healthy, so a lost
  or never-seen store gets nothing written. Its own state is `~/.amc/git-store-backstop.json`.
- The restore is `npm run git:restore -- --live`, run from the project folder. It refuses unless the
  store reads lost, renames the old history aside rather than deleting it, and leaves a
  `.git-restore-in-progress` marker beside the store while it runs.
- Read how far behind the copies are with `npm run git:backstop -- status`; prove a restore works
  with `npm run git:backstop -- drill`.
- Incident kill switch: `AMC_DISABLE_GIT_STORE_LOSS_GUARD=1` turns off the watch, the backstop and
  every writer refusal together.

## Related

- Git guardrails — the rules that stop a session from doing something destructive to git history in
  the first place.
- Worktrees — how the app gives each session its own working copy.