Skip to content

Agent Zero AI framework

Preserve rollback stash identity during self-update

Alessandrod665408d9f22
diff --git a/docker/run/AGENTS.md b/docker/run/AGENTS.md
index a6c08997f..6de0f7ddd 100644
--- a/docker/run/AGENTS.md
+++ b/docker/run/AGENTS.md
@@ -24,6 +24,7 @@
- Runtime startup must ensure `/a0/usr/uploads` exists before supervised services start.
- Runtime startup raises the soft open-file limit toward `A0_NOFILE_LIMIT` (default `65535`) before supervisord starts, bounded by the container hard limit.
- Self-update user-data backups skip Time Travel shadow history under `usr/.time_travel/` and transient Desktop agent state.
+- Self-update rollback stashes use immutable Git object IDs for creation checks and restoration; resolve the matching reflog selector only when dropping that stash, preserving unrelated entries. Failed restoration retains the stash.
- Self-update waits up to 180 seconds for the updated or restored WebUI health check by default; `A0_SELF_UPDATE_HEALTH_TIMEOUT_SECONDS` may override it.
- Successful or already-current self-updates refresh an installed Codex CLI with npm on a best-effort basis; missing CLIs and registry failures must not block Agent Zero startup.
diff --git a/docker/run/fs/exe/self_update_manager.py b/docker/run/fs/exe/self_update_manager.py
index c0d008831..6b658142a 100644
--- a/docker/run/fs/exe/self_update_manager.py
+++ b/docker/run/fs/exe/self_update_manager.py
@@ -663,8 +663,8 @@ def has_local_rollback_changes(repo_dir: Path) -> bool:
return bool(status.strip())
-def get_top_stash_ref(repo_dir: Path) -> str:
- return git_optional_output(repo_dir, "stash", "list", "--format=%gd", "-n", "1")
+def get_top_stash_oid(repo_dir: Path) -> str:
+ return git_optional_output(repo_dir, "stash", "list", "--format=%H", "-n", "1")
def create_rollback_stash(repo_dir: Path, logger: AttemptLogger) -> str | None:
@@ -672,7 +672,7 @@ def create_rollback_stash(repo_dir: Path, logger: AttemptLogger) -> str | None:
logger.log("No tracked or non-ignored untracked changes need rollback protection.")
return None
- previous_top = get_top_stash_ref(repo_dir)
+ previous_top = get_top_stash_oid(repo_dir)
message = f"a0-self-update rollback snapshot {now_iso()}"
run_command(
[
@@ -689,7 +689,7 @@ def create_rollback_stash(repo_dir: Path, logger: AttemptLogger) -> str | None:
logger=logger,
error_message="Failed to save local tracked/untracked changes before updating.",
)
- stash_ref = get_top_stash_ref(repo_dir)
+ stash_ref = get_top_stash_oid(repo_dir)
if not stash_ref or stash_ref == previous_top:
raise RuntimeError("Failed to create the pre-update rollback stash.")
logger.log(
@@ -702,12 +702,18 @@ def create_rollback_stash(repo_dir: Path, logger: AttemptLogger) -> str | None:
def drop_stash(repo_dir: Path, stash_ref: str, logger: AttemptLogger) -> None:
if not stash_ref:
return
- run_command(
- ["git", "-C", str(repo_dir), "stash", "drop", stash_ref],
- cwd=None,
- logger=logger,
- error_message=f"Failed to drop temporary rollback stash {stash_ref}.",
- )
+ # Git accepts an object ID for apply, but drop requires a current reflog selector.
+ for entry in git_output(repo_dir, "stash", "list", "--format=%H %gd").splitlines():
+ oid, selector = entry.split(" ", 1)
+ if oid == stash_ref:
+ run_command(
+ ["git", "-C", str(repo_dir), "stash", "drop", selector],
+ cwd=None,
+ logger=logger,
+ error_message=f"Failed to drop temporary rollback stash {stash_ref}.",
+ )
+ return
+ logger.log(f"Rollback stash {stash_ref} is no longer listed; other stashes were kept.")
def apply_stash(repo_dir: Path, stash_ref: str, logger: AttemptLogger) -> None:
diff --git a/extensions/python/startup_migration/AGENTS.md b/extensions/python/startup_migration/AGENTS.md
index d3ffc39a0..4f87e56e7 100644
--- a/extensions/python/startup_migration/AGENTS.md
+++ b/extensions/python/startup_migration/AGENTS.md
@@ -14,6 +14,7 @@
- Preserve user data and create backups or reversible paths when changing durable state.
- Keep long-running work bounded and observable.
- `_10_self_update_manager.py` may replace `/exe/self_update_manager.py` from the repository copy when the installed runtime updater is stale; it must validate required safety markers and keep a backup before replacement.
+- Required updater capabilities include immutable rollback-stash identity (`get_top_stash_oid`), so runtimes using moving stash selectors are upgraded on startup.
- After synchronizing a stale self-update manager, `_10_self_update_manager.py` starts that manager's best-effort Codex CLI refresh in the background so the update that introduces the hook does not need a second restart.
## Work Guidance
diff --git a/extensions/python/startup_migration/_10_self_update_manager.py b/extensions/python/startup_migration/_10_self_update_manager.py
index fff24cc1c..78df14e4c 100644
--- a/extensions/python/startup_migration/_10_self_update_manager.py
+++ b/extensions/python/startup_migration/_10_self_update_manager.py
@@ -23,6 +23,7 @@ SELF_UPDATE_MANAGER_SOURCE_PATH = Path(
)
BACKUP_SUFFIX = ".startup-migration-backup"
REQUIRED_RUNTIME_MARKERS = (
+ "def get_top_stash_oid(",
"def should_include_usr_backup_entry(",
"Skipping non-regular usr backup entry",
"def clean_transient_desktop_agent_state(",
diff --git a/tests/test_self_update_runtime_sync.py b/tests/test_self_update_runtime_sync.py
index fc30bba02..25588e8a3 100644
--- a/tests/test_self_update_runtime_sync.py
+++ b/tests/test_self_update_runtime_sync.py
@@ -19,6 +19,10 @@ from pathlib import Path
REPO_DIR = Path("/a0")
+def get_top_stash_oid(repo_dir):
+ return ""
+
+
def should_include_usr_backup_entry(source_file, logger):
logger.log("Skipping non-regular usr backup entry")
return False
@@ -75,6 +79,21 @@ def test_self_update_runtime_sync_accepts_repository_manager_source(tmp_path):
assert target.read_text(encoding="utf-8") == source.read_text(encoding="utf-8")
+def test_self_update_runtime_sync_upgrades_moving_stash_selectors(tmp_path):
+ source = PROJECT_ROOT / "docker" / "run" / "fs" / "exe" / "self_update_manager.py"
+ target = tmp_path / "self_update_manager.py"
+ stale = SAFE_SOURCE.replace("get_top_stash_oid", "get_top_stash_ref")
+ target.write_text(stale, encoding="utf-8")
+
+ result = migration.ensure_self_update_manager_runtime_current(
+ target_path=target, source_path=source,
+ )
+
+ assert result["updated"] is True
+ assert target.read_text(encoding="utf-8") == source.read_text(encoding="utf-8")
+ assert target.with_name(target.name + migration.BACKUP_SUFFIX).read_text() == stale
+
+
def test_self_update_runtime_sync_starts_codex_refresh(monkeypatch, tmp_path):
calls = []
manager_path = tmp_path / "self_update_manager.py"
diff --git a/tests/test_self_update_tag_filter.py b/tests/test_self_update_tag_filter.py
index f4c2aab34..c27f4bdf1 100644
--- a/tests/test_self_update_tag_filter.py
+++ b/tests/test_self_update_tag_filter.py
@@ -1,5 +1,6 @@
import importlib.util
import socket
+import subprocess
import sys
import tempfile
import types
@@ -29,6 +30,70 @@ def load_self_update_manager():
return module
[email protected]("action", ["apply", "drop", "conflict"])
+def test_rollback_stash_preserves_identity_and_unrelated_entries(tmp_path, action):
+ manager = load_self_update_manager()
+ logger = manager.NullLogger()
+
+ def git(*args):
+ return subprocess.run(
+ ["git", "-C", str(tmp_path), *args],
+ check=True, capture_output=True, text=True,
+ ).stdout.strip()
+
+ git("init", "-q")
+ git("config", "user.name", "Updater test")
+ git("config", "user.email", "[email protected]")
+ tracked = tmp_path / "tracked.txt"
+ staged = tmp_path / "staged.txt"
+ tracked.write_text("original\n")
+ staged.write_text("original\n")
+ (tmp_path / ".gitignore").write_text("ignored.txt\n")
+ git("add", ".")
+ git("commit", "-qm", "Fixture")
+ assert manager.create_rollback_stash(tmp_path, logger) is None
+
+ tracked.write_text("older user change\n")
+ older = manager.create_rollback_stash(tmp_path, logger)
+ assert older == git("rev-parse", "refs/stash")
+
+ tracked.write_text("rollback unstaged\n")
+ staged.write_text("rollback staged\n")
+ git("add", "staged.txt")
+ (tmp_path / "untracked.txt").write_text("rollback untracked\n")
+ (tmp_path / "ignored.txt").write_text("keep ignored\n")
+ rollback = manager.create_rollback_stash(tmp_path, logger)
+ assert rollback == git("rev-parse", "refs/stash")
+ assert rollback != older
+ assert git("status", "--porcelain") == ""
+ assert (tmp_path / "ignored.txt").read_text() == "keep ignored\n"
+
+ (tmp_path / "newer.txt").write_text("unrelated newer change\n")
+ git("stash", "push", "--include-untracked", "-m", "Unrelated newer stash")
+ newer = git("rev-parse", "refs/stash")
+ if action == "conflict":
+ tracked.write_text("conflicting change\n")
+ git("add", "tracked.txt")
+ git("commit", "-qm", "Conflicting update")
+ with pytest.raises(RuntimeError, match="Failed to restore"):
+ manager.apply_stash(tmp_path, rollback, logger)
+ assert git("stash", "list", "--format=%H").splitlines() == [newer, rollback, older]
+ return
+ if action == "apply":
+ manager.apply_stash(tmp_path, rollback, logger)
+ assert tracked.read_text() == "rollback unstaged\n"
+ assert staged.read_text() == "rollback staged\n"
+ assert (tmp_path / "untracked.txt").read_text() == "rollback untracked\n"
+ assert git("diff", "--cached", "--name-only") == "staged.txt"
+ assert git("diff", "--name-only") == "tracked.txt"
+ else:
+ manager.drop_stash(tmp_path, rollback, logger)
+ assert git("status", "--porcelain") == ""
+ assert git("stash", "list", "--format=%H").splitlines() == [newer, older]
+ manager.drop_stash(tmp_path, rollback, logger)
+ assert git("stash", "list", "--format=%H").splitlines() == [newer, older]
+
+
def test_self_update_selector_tags_use_two_segments_and_v1_floor():
assert self_update.is_valid_selector_tag("v1.0")
assert self_update.is_valid_selector_tag("v12.34")