Skip to content

openamer/openamer / optional-skills/autonomous-ai-agents/openamer-update-recovery

openamer-update-recovery

Verified

Recover 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 update printed ✗ ZIP update failed / Git update failed / a non-zero exit.
  • Every openamer launch now prints ⚠ A previous openamer update was interrupted mid-install — finishing dependency installation now... and then ✗ Could not auto-recover the interrupted install.
  • openamer --version shows "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.
  • openamer itself crashes on import (ModuleNotFoundError / ImportError from openamer_cli.env_loader, openamer_cli.config, dotenv, yaml). Start with openamer doctor --runtime — that path is stdlib-only and still runs when the rest of the CLI cannot be imported.

Prerequisites

  • A working git checkout of the install (the git stage usually succeeds even when deps fail).
  • The managed uv binary (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.py clears it, and only on success.
  • The launch-time repair records attempts=N in the marker and stops after 3 failed attempts, so an offline machine cannot reinstall on every launch forever. openamer doctor --runtime --fix ignores 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

  1. 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
    
  2. Run the full .[all] reinstall manually (this is what the auto-recovery tries and fails at). Use the managed uv binary, not a bare pip:

    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]"
    
  3. Delete the marker once the install succeeds:

    rm -f .update-incomplete .update-incomplete.lock .lazy-refresh-incomplete
    
  4. Clean up update leftovers (staging/old dirs the ZIP fallback leaves):

    rm -rf apps.openamer-update-staging apps.openamer-update-old
    

Pitfalls

  • openamer update says "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 on openamer update to clear it when there's nothing to pull.
  • The agent is running INSIDE the desktop app it needs to kill — you cannot taskkill the app from your own session without killing yourself mid-turn. Solution: write a detached PowerShell script that (a) sleeps a few seconds, (b) kills OpenAmer.exe + openamer.exe, (c) runs the manual reinstall with VIRTUAL_ENV set, (d) deletes the markers on success, (e) restarts openamer desktop, and launch it with Start-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 (PowerShell Out-File writes UTF-16 — read it back with iconv -f UTF-16LE -t UTF-8 or tr -d '\000').
  • [WinError 5] Zugriff verweigert on the apps folder — the running desktop app (or another OpenAmer window) holds file locks on apps/, 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 run openamer update from 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 missing VIRTUAL_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 update command 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.

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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall