Agent install serves a STALE manifest from the cached main.tar.gz when a manifest change leaves registry-index.json untouched (residual of #254)

[pawellisowski]

Summary

A manifest change made inside the rolling main.tar.gz (e.g. flipping a status: field) does not bust the agent-install tarball cache, because the cache key only rotates when registry-index.json changes. So users who cached main.tar.gz before the manifest change keep installing the stale manifest indefinitely (no TTL on the tarball cache). This is the residual case that #254's content-fingerprint fix does not cover.

Concrete, reproduced repro (live)

#269 flipped 20-agents/_core/file/manifest.yaml status: planned → available (2026-06-25) but did not touch registry-index.json (last changed by #257, 2026-06-18). On a machine whose ~/.aware/cache/agents/tarball-<sha>.tar.gz was cached on 2026-06-18:

$ aware agent install file
✓ installed file
$ grep '^status:' ~/.aware/agents/file/manifest.yaml
status: planned            # ← STALE (main has `available`)
$ aware app run <app-with-a-file/write-node>
error: node "w" references agent "file", which is declared but not yet runnable
       (no shipped/installable transport binary)
error: validation failed: [E_APP_AGENT_UNAVAILABLE]

# purge the URL+fingerprint-keyed tarball cache, reinstall:
$ rm ~/.aware/cache/agents/tarball-*.tar.gz && aware agent uninstall file && aware agent install file
$ grep '^status:' ~/.aware/agents/file/manifest.yaml
status: available          # ← correct; app run then works

The file/write/write-csv verbs are wired in-process (#268) and aware agent invoke file write-csv works — only aware app run's validate gate rejects the stale-planned manifest. So the binary is fine; the manifest delivery is stale.

Root cause (file:line)

• cli/src/install/registry.rs:58 — tarball cache file = tarball-{sha256(tarball_url + index.snapshot_fingerprint())}.tar.gz.
• cli/src/registry/index.rs snapshot_fingerprint() hashes the serialized index (registry-index.json). A change inside main.tar.gz that leaves registry-index.json byte-identical produces the same fingerprint → same cache filename → the stale archive is reused (registry.rs:63 if cache_file.is_file() { copy }).
• The tarball cache has no TTL (unlike the index/catalog, which carry a 1h TTL in cli/src/registry/fetch.rs:19).

The code comment at registry.rs:48-57 already anticipates this: updated-at is "the registry's manual refresh lever" — but nothing bumps it when a manifest inside the tarball changes, so the lever is never pulled.

Impact

Any manifest edit that ships via the rolling main.tar.gz without an accompanying registry-index.json change (status flips, description/keyword fixes, input/output schema tweaks) silently fails to reach users with a warm cache. The file agent is a live example — it breaks file/write apps with a confusing E_APP_AGENT_UNAVAILABLE even though the runtime supports the verb.

Suggested fixes (pick one)

1. Auto-bump registry-index.json updated-at in CI/release whenever any 20-agents/**/manifest.yaml changes (or on every release tag) — pulls the documented lever automatically.
2. Add a TTL to the tarball cache mirroring the index's 1h TTL (fetch.rs:19), so a warm cache self-refreshes (bounded re-download, not per-agent).
3. Key the cache on the archive's real content (ETag / commit SHA of refs/heads/main) instead of the index fingerprint.

Mitigation already applied

PR # bumps updated-at now so the current stale file caches bust on the next install (live, 1h TTL). That's a one-off; this issue tracks the systemic fix so it can't recur.

Cross-ref: #254 (the prior fingerprint fix this is a residual of), #268/#269 (the file agent), #243 (the per-agent re-download optimization the shared cache serves).

[pawellisowski]

Fixed in #272 (merged to main as fae89253d) — ready to test.

The agent-install tarball cache now carries the same 1h CACHE_TTL the index/catalog use, so an in-archive manifest change (a status: flip, a keyword/description fix) that leaves registry-index.json byte-identical self-heals within an hour instead of being served stale forever. The snapshot fingerprint still busts the cache instantly on any index change.

How to verify (the issue's repro): with a warm ~/.aware/cache/agents/tarball-*.tar.gz, an in-archive manifest change is served stale while the cache is fresh (bounded, by design), then picked up automatically once the cache ages past 1h — no manual rm of the cache needed. Verified end-to-end on the built binary (temp AWARE_HOME + file:// registry): status: planned → flipped to available inside the same archive → self-heals to available after the TTL.

Resilience was hardened under Codex review: a stale-but-present cache is reused if a refresh fails offline / times out / is corrupt, and a refreshed archive that outran the cached index falls back to the prior cache rather than failing the install.

Note this lands in main but is not yet released — it reaches users on the next @aware-aeco/cli release. Close on pass, or label qa-rejected if it fails.

[pawellisowski]

Shipped in v0.82.0 (npm @aware-aeco/cli@0.82.0, GitHub Release) — update (npm i -g @aware-aeco/cli@latest) and test. Close on pass, or label qa-rejected if it fails.