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 doing something destructive to git history.
• Isolated session view — how each session gets its own working copy.