openamer/openamer / optional-skills/autonomous-ai-agents/openamer-update-recovery
openamer-update-recovery
VerifiedRecover from a failed or broken `openamer update`.
OpenAmer Update Recovery Skill
Recover from a failed or interrupted openamer update. The update is a
multi-stage process (git pull → dependency install → optional ZIP fallback),
and any stage can fail partway, leaving the install in a half-updated state
that then misbehaves on every subsequent launch. This skill diagnoses the
marker lifecycle and walks through a clean reinstall.
When to Use
openamer updateprinted✗ ZIP update failed/Git update failed/ a non-zero exit.- Every
openamerlaunch now prints⚠ A previous openamer update was interrupted mid-install — finishing dependency installation now...and then✗ Could not auto-recover the interrupted install. openamer --versionshows "Up to date" but the recovery warning still fires.- A launch prints
⚠ Automatic dependency repair already failed 3 times — not retrying— the bounded launch-time repair gave up (usually an unreachable package index) and now wants an explicit repair. openameritself crashes on import (ModuleNotFoundError/ImportErrorfromopenamer_cli.env_loader,openamer_cli.config,dotenv,yaml). Start withopenamer doctor --runtime— that path is stdlib-only and still runs when the rest of the CLI cannot be imported.
Prerequisites
- A working
gitcheckout of the install (the git stage usually succeeds even when deps fail). - The managed
uvbinary (see "Locating the install" below). - Shell access to the install directory.
Locating the install
The install directory and the managed uv binary are platform-specific. Do
NOT hardcode ~/.openamer/openamer-agent — that is the data directory, not
the install. The reliable way to find the install directory is:
openamer --version
# → "Install directory: <path>" ← this is the install dir (contains openamer_cli/)
Typical locations:
- Windows (native):
%LOCALAPPDATA%\openamer-laptop\openamer-agent - Linux/macOS (managed):
~/.openamer/openamer-agent(or$OPENAMER_HOME/openamer-agent)
The managed uv binary lives at $OPENAMER_HOME/bin/uv (on Windows
%LOCALAPPDATA%\openamer-laptop\bin\uv.exe), NOT inside the install dir.
How to Run
Run the recovery steps below with the terminal tool. On Windows the venv
Python lives at venv/Scripts/python.exe (NOT venv/bin/). The VIRTUAL_ENV
env var is required so uv targets the project venv instead of creating a new
one.
Quick Reference
cd <install-dir> # from `openamer --version` → "Install directory:"
VIRTUAL_ENV="$(pwd)/venv" <uv> pip install -e ".[all]"
rm -f .update-incomplete .update-incomplete.lock .lazy-refresh-incomplete
rm -rf apps.openamer-update-staging apps.openamer-update-old
openamer --version # must print version with NO ⚠ warning
Procedure
The marker lifecycle (root cause of the "stuck" symptom)
A failed update writes a breadcrumb file at the install directory root
(the directory that contains openamer_cli/), NOT under $OPENAMER_HOME.
On every launch, openamer_cli/main.py::_recover_from_interrupted_install()
sees the marker and tries to finish the install. If that recovery itself
fails, it leaves the marker in place, so the next launch tries again — the
stdlib-only early pass stops after 3 failed attempts and points at
openamer doctor --runtime --fix, but the marker (and so the warning) stays
until an install actually succeeds. The fix is to make the install actually
succeed, THEN delete the marker.
Key facts (from openamer_cli/main.py and _early_recovery.py):
.update-incomplete→ core.[all]install was interrupted. Recovered ONLY by a full.[all]reinstall; narrow import-probe repair never clears it..lazy-refresh-incomplete→ lazy-backend refresh may have corrupted packages; recovered by import-probe repair..update-incomplete.lock→ single-flight guard (O_EXCL); a stale lock is broken after 1 hour (3600s).- The marker is intentionally NOT cleared by the stdlib-only early-recovery
pass — only the full recovery in
main.pyclears it, and only on success. - The launch-time repair records
attempts=Nin the marker and stops after 3 failed attempts, so an offline machine cannot reinstall on every launch forever.openamer doctor --runtime --fixignores that limit.
Diagnose before you reinstall (works when the CLI is unimportable)
openamer doctor --runtime # interpreter, profile, uv.lock provenance, import probes
openamer doctor --runtime --fix # force-reinstall the broken core packages into that interpreter
# equivalent, without the launcher entry point:
python -m openamer_cli._early_recovery --fix
--runtime is stdlib-only and is dispatched before openamer_cli.main
imports third-party packages, so it still works in the failure state that makes
every other subcommand crash. It never touches another profile or venv: the
repair targets the interpreter that produced the diagnosis, and it prints that
path (repair into …) plus the uv.lock / pyproject.toml it read. Read the
probe table before reinstalling the world — a BROKEN row names the exact
package and the exact import error.
Recovery steps
-
Confirm the code is actually current — the git stage often succeeds even when deps fail:
cd <install-dir> git log --oneline -3 openamer --version # shows "Up to date" if git pulled fine -
Run the full
.[all]reinstall manually (this is what the auto-recovery tries and fails at). Use the managed uv binary, not a barepip:cd <install-dir> VIRTUAL_ENV="$(pwd)/venv" <uv> pip install -e ".[all]" # fallback if uv is missing: ./venv/Scripts/python.exe -m pip install -e ".[all]" -
Delete the marker once the install succeeds:
rm -f .update-incomplete .update-incomplete.lock .lazy-refresh-incomplete -
Clean up update leftovers (staging/old dirs the ZIP fallback leaves):
rm -rf apps.openamer-update-staging apps.openamer-update-old
Pitfalls
openamer updatesays "Already up to date!" but the marker is still there — when git has no new commit, the update path skips the dependency reinstall entirely and does NOT clear.update-incomplete. The marker then keeps firing the recovery warning on every launch. Fix: run the manual.[all]reinstall yourself (step 2), then delete the marker. Do NOT rely onopenamer updateto clear it when there's nothing to pull.- The agent is running INSIDE the desktop app it needs to kill — you
cannot
taskkillthe app from your own session without killing yourself mid-turn. Solution: write a detached PowerShell script that (a) sleeps a few seconds, (b) killsOpenAmer.exe+openamer.exe, (c) runs the manual reinstall withVIRTUAL_ENVset, (d) deletes the markers on success, (e) restartsopenamer desktop, and launch it withStart-Process powershell -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-File',... -WindowStyle Hidden. The script survives your session's death and finishes the job. Log every step to a file so you can verify afterward (PowerShellOut-Filewrites UTF-16 — read it back withiconv -f UTF-16LE -t UTF-8ortr -d '\000'). [WinError 5] Zugriff verweigerton theappsfolder — the running desktop app (or another OpenAmer window) holds file locks onapps/, so the ZIP fallback can't rename it. This is why the ZIP path fails on Windows. The git path is the primary path and works fine; the ZIP failure is non-fatal. To avoid it entirely, close the desktop app before updating, or runopenamer updatefrom a separate terminal.Failed to inspect Python interpreter ... venv\Scripts\python.exe— this error is often a red herring: the interpreter exists and works. The real blocker is usually the file-lock or a missingVIRTUAL_ENV. Test the interpreter directly (./venv/Scripts/python.exe -c "print('ok')") before assuming the venv is broken.- Don't just delete the marker without a successful reinstall. The marker exists because the install is genuinely incomplete. Deleting it first can leave a half-installed venv that fails later. Reinstall → verify → then delete.
uv pip install -e .(base only) is not enough — the recovery path requires.[all](extras). A base-only install leaves the marker's condition unmet.- The
openamer updatecommand restarts the gateway and kills running agents — it's flagged for approval. Expect the running session to be affected.
Verification
openamer --version # should print version + "Up to date" with NO ⚠ warning
ls .update-incomplete .update-incomplete.lock .lazy-refresh-incomplete
# → "No such file or directory" for all three means the recovery is complete
Related
The bundled openamer-agent skill (protected) is the umbrella for general
OpenAmer usage; this skill is the focused companion for the self-update
failure mode. If openamer-agent gains a troubleshooting section for this,
this skill can be absorbed into it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |