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.

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 —
forever. 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.

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.