instar 0.28.0 → 0.28.2

package/upgrades/0.28.1.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — v0.28.1
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Gate Failure Diagnostics** — When a job's gate command fails, the scheduler now captures and logs the exit code, stderr output, and the gate command itself in the event metadata. Previously, gate failures were silently swallowed with only "gate check returned nothing to do" — making it impossible to diagnose why jobs were being skipped.
+
+Additionally, gate skips are now recorded in the SkipLedger (previously only quota, paused, claimed, and machine-scope skips were tracked). The new `gate` skip reason appears in skip reports and the auto-tune system.
+
+**Memory Export Gate Auth Fix** — The memory-export job's gate command referenced an undefined `$AUTH` shell variable. The gate now resolves the auth token inline from the agent's config file, matching the pattern used by the job's execute script.
+
+## What to Tell Your User
+
+- **Better job skip visibility**: "If your scheduled jobs are being skipped and you are not sure why, the skip events now include the actual error from the gate check. You can see these in the event log or skip ledger."
+
+- **Memory export reliability**: "The memory export job had a gate that would always fail silently due to a missing authentication token. This is now fixed — memory exports should run on schedule."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Gate skip diagnostics | Automatic — check event log for `job_gate_skip` events with `exitCode` and `stderr` metadata |
+| Gate skip in SkipLedger | `GET /jobs/report` now includes gate skips in skip counts |

package/upgrades/0.28.2.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — v0.28.2
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Lifeline Shutdown Crash-Proofing** — The shutdown handler in both the lifeline and server now wraps `unregisterAgent`, `stopHeartbeat`, and other cleanup steps in try-catch. Previously, an ELOCKED error from the agent registry during SIGTERM would crash the lifeline with an unhandled exception. This confused launchd's KeepAlive restart logic and could leave the agent in a "spawn scheduled" limbo state indefinitely. The lifeline also now installs global `uncaughtException` and `unhandledRejection` handlers that specifically catch ELOCKED errors — the lifeline will never crash from registry lock contention again.
+
+**409 Conflict Resolution** — When a stale Telegram long-poll connection causes persistent 409 Conflict errors ("another bot instance is polling"), the lifeline now actively tries to reclaim exclusive polling every 20 failures by calling deleteWebhook followed by a zero-timeout getUpdates. Previously, the lifeline would back off to 60 seconds and never recover, rendering the agent permanently unreachable until a manual restart.
+
+**Settings JSON Self-Healing** — Both the lifeline startup and the ServerSupervisor preflight checks now validate `.claude/settings.json` for parseable JSON. If unresolved git merge conflict markers are detected, the file is auto-repaired by stripping the conflict markers (with a backup saved). This was the root cause of a complete agent outage where every Claude Code session crashed on startup due to invalid JSON, while the lifeline and server showed no errors — the agent appeared alive but never responded to messages.
+
+## What to Tell Your User
+
+- **More resilient agent recovery**: "Your agent is now much harder to take down. Even if something goes wrong during a restart, the lifeline will survive and keep your agent reachable. Previously, a lock file contention during shutdown could permanently strand the agent."
+
+- **Automatic Telegram recovery**: "If your agent's Telegram connection gets into a conflict state — for example after a machine sleep or a crash — it will now automatically recover instead of requiring a manual restart."
+
+- **Config corruption protection**: "If a git sync causes a merge conflict in your agent's settings file, the system will now detect and auto-repair it. Previously, this could silently prevent all sessions from starting while everything else appeared healthy."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Shutdown crash-proofing | Automatic — ELOCKED errors during shutdown are caught and logged |
+| 409 conflict resolution | Automatic — reclaim attempt every 20 consecutive 409 errors |
+| Settings JSON validation | Automatic — preflight check on every server/lifeline start |
+| Global ELOCKED safety net | Automatic — uncaught ELOCKED errors logged but don't crash lifeline |
+