openamer-update-recovery

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
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

```bash
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:
   ```bash
   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`:
   ```bash
   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:
   ```bash
   rm -f .update-incomplete .update-incomplete.lock .lazy-refresh-incomplete
   ```

4. **Clean up update leftovers** (staging/old dirs the ZIP fallback leaves):
   ```bash
   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

From openamer/openamer, MIT.

More from openamer/openamer