instar 1.3.680 → 1.3.682

package/upgrades/coldstart-lifeline-fallback.eli16.md

@@ -0,0 +1,49 @@
+# Cold-Start Lifeline Fallback — ELI16 overview
+
+## The problem in plain words
+
+When you send a message to one of your agent's topics, the agent has to *start a
+session* to read and answer it. Usually that just works. But sometimes it can't
+start one right then — maybe too many sessions are already running (a hard limit),
+maybe the machine is low on memory or under heavy load, or maybe the startup hit an
+unexpected error.
+
+Before this change, when that happened you'd either get silence, or a bare, unhelpful
+line like "Having trouble starting a session right now." Worse, one version told you
+to "increase maxSessions in your config" — asking *you* to go edit a settings file.
+That's backwards: the agent is the thing with the tools to free up resources and fix
+the problem. You shouldn't have to.
+
+## What this change does
+
+Now, when the agent genuinely can't start (or restart) a session for a topic, you get
+ONE clear, friendly reply that does three things:
+
+1. **Says WHY in plain English** — "I'm already running the maximum number of sessions
+   at once," or "the machine is under resource pressure right now," or an honest
+   "unexpected start-up error." No jargon, no config keys.
+2. **Points you to your Lifeline topic** — the one topic that's guaranteed to always be
+   reachable. That's the place to go when a normal topic is stuck.
+3. **Hands you a ready-to-paste message** — a pre-written line you can copy straight
+   into the Lifeline that describes exactly what failed, so the agent can diagnose and
+   free resources fast. You don't have to explain anything yourself.
+
+If the failing topic *is* your Lifeline, it doesn't tell you to go elsewhere — it says
+you're already in the right place and it'll start freeing resources. If you have no
+Lifeline configured, it still tells you why and reassures you that your message isn't
+lost — just resend once things settle.
+
+## Why it's built this way
+
+This is the "G1" half of a constitutional standard called **"The Agent Is Always
+Reachable."** The core idea: the agent must never go silently unreachable, because the
+agent itself is the solution — it holds the tools to diagnose and free resources, so it
+has to stay reachable to use them. The reply is sent on a *deterministic* delivery path
+(a direct send), never through the smart message-review gate, because that gate could
+itself fail under the very resource pressure we're trying to report.
+
+It's an always-on safety floor with no on/off switch — the standard forbids hiding
+reachability behind a flag. Under the hood it's a small, well-tested message builder
+wired into the two places a session-start can fail (a fresh spawn and a restart), plus
+a CLAUDE.md note so any agent can explain "why did I get a go-to-lifeline message?" if
+you ask.

package/upgrades/reaper-squash-merge-aware.eli16.md

@@ -0,0 +1,43 @@
+# Squash-merge-aware worktree reaper — ELI16 overview
+
+## The problem in plain words
+
+When the agent works on a change, it makes a "worktree" — a full copy of the codebase
+in its own folder — so different jobs don't trip over each other. Each one is hundreds
+of megabytes. After the change is merged and shipped, that folder is dead weight: the
+work is safely in the main branch, so the copy can be deleted.
+
+A background cleaner (the "reaper") is supposed to delete those finished folders. But it
+had a blind spot. To decide "is this branch's work already in main?", it compared the
+branch's commits to main commit-by-commit (using a git trick called patch-id). That
+works when a branch is merged normally — but this project **squash-merges**: it mashes
+all of a branch's commits into ONE new commit on main. That single squashed commit has a
+different fingerprint than the original commits, so the reaper couldn't recognize the
+work as merged. It played it safe and **kept the folder forever**.
+
+Result: merged-but-unrecognized folders piled up — on this machine, hundreds of them,
+over 100 GB of disk. That bloat is part of what made the machine slow and, eventually,
+contributed to a crash.
+
+## What this change does
+
+The reaper now has a second way to tell a branch is merged: it asks GitHub. Once per
+cleanup sweep it fetches the list of **merged pull requests** and the exact commit each
+one merged. If a folder's branch has a merged PR, AND the folder is sitting on exactly
+that same commit, the reaper knows the work is in main and the folder is safe to delete.
+
+Two safety rules make this trustworthy:
+- **Exact-commit match.** If you added new commits to the branch AFTER its PR merged,
+  the folder's commit won't match the merged one, so it's still KEPT — new work is never
+  thrown away.
+- **Fail-safe.** If GitHub can't be reached (offline, not logged in, not a GitHub repo),
+  the reaper simply falls back to the old commit-by-commit check and keeps the folder.
+  It never deletes on a guess.
+
+It's still off by default and runs in dry-run first (it tells you what it WOULD delete
+before it deletes anything), and there's an off-switch (`githubMergeCheck: false`) to
+turn off the GitHub call entirely. The GitHub lookup is just ONE call per sweep, cached,
+so it's cheap.
+
+The net effect: when you turn the reaper on, it can finally reclaim the squash-merged
+folders that were stuck forever — recovering the disk that was quietly disappearing.

package/upgrades/side-effects/coldstart-lifeline-fallback.md

@@ -0,0 +1,85 @@
+# Side-Effects Review — Cold-Start Lifeline Fallback (G1)
+
+**Version / slug:** `coldstart-lifeline-fallback`
+**Date:** `2026-06-26`
+**Author:** `echo`
+**Tier:** 1 (enhances an EXISTING always-on user-notice on the inbound cold-start
+failure path; reuses the already-merged "Agent Is Always Reachable" standard #1288;
+no new authority, no new gate, no protocol/security change)
+
+## Summary of the change
+
+G1 (the user-facing arm) of the constitutional standard **"The Agent Is Always
+Reachable"** corollary (2), *no silent resource rejection*. When a user messages a
+topic and the system genuinely cannot start (cold spawn) OR restart a session for it,
+the existing catch already sent a generic notice — but it (a) did not point to the
+Lifeline, (b) did not hand a copy-paste debug message, and (c) leaked dev jargon
+("increase maxSessions in your config"). This change extracts a pure, unit-tested
+message builder (`src/messaging/ColdStartFallbackReply.ts`) that classifies WHY the
+start failed (`session-limit` / `resource-pressure` / `start-failure`) and composes a
+plain-English reply with the Lifeline pointer + a pre-written copy-paste debug block,
+and wires it into BOTH inbound failure paths in `src/commands/server.ts`. Migration
+parity: a `migrateClaudeMd` section (existing agents) + a `generateClaudeMd` template
+section (new agents) so any agent can explain the behavior. Files:
+`src/messaging/ColdStartFallbackReply.ts` (new), `src/commands/server.ts` (two catch
+sites), `src/core/PostUpdateMigrator.ts` (CLAUDE.md section), `src/scaffold/templates.ts`
+(template section), plus three test files (logic, wiring-integrity, migration).
+
+## Decision-point inventory
+
+- The two inbound failure catches (`onTopicMessage` cold-spawn `.catch` and restart
+  `.catch`) — **pass-through**. They already FIRED a notice; this only changes the
+  *content* of the message (and replaces the string-match branch with the classifier).
+  No control-flow change: still one `telegram.sendToTopic(topicId, …)` on failure.
+
+## 1. Over-block
+
+**No block/allow surface — not applicable.** The change produces a user-facing message
+on an already-failing path; it never blocks, delays, or rejects any session, message,
+or spawn. The spawn/restart decision is entirely unchanged (the failure already
+happened by the time the builder runs).
+
+## 2. Under-block
+
+**Not applicable** — no gate. The closest "miss" is a misclassified reason word, which
+only changes the wording (the notice still fires and still points to the Lifeline). The
+classifier is a SIGNAL (help text), not authority — both sides of each classification
+branch are unit-tested.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. The failure reason (the thrown error) and the delivery primitive
+(`telegram.sendToTopic`, `telegram.getLifelineTopicId`) are both already in scope at the
+catch site; composing the message there — via a pure builder that has no I/O — is the
+right level. The builder is isolated in `src/messaging/` so it is unit-testable without
+standing up the server.
+
+## 4. Signal vs authority compliance
+
+The reply is **pure signal** — a help message on a deterministic delivery path. It
+carries zero blocking authority: it cannot hold, delay, or release a session. The
+session's fate is decided entirely by the unchanged `SessionManager.spawnSession`
+throw. This is the signal-vs-authority split the principle demands.
+
+## 5. Interactions
+
+- **Deterministic path (deliberate):** delivery is the direct `sendToTopic`, NOT the
+  LLM tone gate — per the standard, the notice must not be blockable by the very
+  pressure it reports (a tone gate failing closed under load would swallow it).
+- **Double-fire:** unchanged. The existing `spawningTopics` guard + the single `.catch`
+  still fire at most one notice per failed attempt.
+- **Same-topic-is-lifeline:** handled — when the failing topic IS the Lifeline, the
+  message does not tell the user to go elsewhere (tested).
+- **No-lifeline-configured:** degrades to "why + honest retry guidance" (tested).
+
+## 6. External surfaces
+
+- **User:** the agent's own Telegram topic — same `sendToTopic` primitive, same
+  topic, same priority as the message it replaces. No new external call shape.
+- **No new config, route, hook, or credential.** Always-on (the standard forbids
+  dark-shipping reachability); the only "surface" change is better message text.
+
+## 7. Rollback
+
+Pure code + docs. Reverting the commit restores the prior generic notice. No state
+migration to undo (the CLAUDE.md section is idempotent and additive).

package/upgrades/side-effects/reaper-squash-merge-aware.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — Squash-merge-aware worktree reaper
+
+**Version / slug:** `reaper-squash-merge-aware`
+**Date:** `2026-06-26`
+**Author:** `echo`
+**Tier:** 1 — enhances an EXISTING merged-detection on the AgentWorktreeReaper (which
+ships OFF + dry-run by default). Adds a fail-safe, conservative network SIGNAL + a config
+off-switch. No new authority, no new gate, no new route. The reaper's safety contract
+("NEVER delete unmerged work") is strengthened, not weakened.
+
+## Summary of the change
+
+The reaper's merged-check used `git cherry` (patch-id equivalence) ONLY, which the code
+itself documents cannot detect MULTI-commit squash-merges — the disk-accumulation root
+cause (squash-merged worktrees kept forever; ~118GB/290 observed). Added a SECOND,
+conservative signal: `fetchMergedPrHeadOids()` does ONE `gh pr list --state merged`
+call per sweep (cached 60s) → a `headRefName→headRefOid` map; `isMerged` treats a
+worktree as merged only when its branch has a merged PR whose head OID EXACTLY matches
+the worktree HEAD. Files: `agentWorktreeGit.ts` (the fetcher + the cached map + the
+enhanced `isMerged`), `AgentWorktreeReaper.ts` (config field `githubMergeCheck`,
+default true), `types.ts` (config type), `server.ts` (plumb the flag),
+`PostUpdateMigrator.ts` (awareness). Tests: 9 new (`fetchMergedPrHeadOids` parse/fail-safe,
+`isMerged` PR-map both sides + oid-mismatch keep + disabled-no-call).
+
+## 1. Over-block (over-KEEP)
+
+Possible: a genuinely-merged worktree is still KEPT (e.g. gh offline, PR list older than
+`--limit 500`, branch renamed). This is the SAFE direction — a kept worktree wastes disk
+but loses nothing. Fully acceptable; it is exactly today's behavior on any gh failure.
+
+## 2. Under-block (the deletion-safety risk — the one that matters)
+
+The hard rule is NEVER delete unmerged work. The new signal can only ADD a "merged"
+verdict, so the question is: can it false-positive? Guards: (a) it requires an actual
+MERGED PR for the branch (authoritative — the content is in main); (b) it requires the
+worktree HEAD to EXACTLY equal the PR's merged head OID, so a branch with commits added
+AFTER the merge (unmerged work on top) is KEPT (tested); (c) the upstream `isClean` gate
+still independently blocks any uncommitted/untracked changes; (d) fail-safe to cherry-only
+on any gh error. A reused branch name resolves to the NEWEST merged PR, and the exact-OID
+match still gates deletion. Both sides tested.
+
+## 3. Level-of-abstraction fit
+
+Correct layer — the change lives entirely in the deps factory (`makeAgentWorktreeReaperDeps`);
+the pure classifier (`AgentWorktreeReaper.evaluate`) is untouched and stays fake-testable.
+The gh call is lazy (only when `git cherry` says unmerged) and cached (one call per sweep).
+
+## 4. Signal vs authority compliance
+
+The merged-PR map is a SIGNAL consumed by the existing deterministic reaper gate-chain;
+it has no block/allow surface of its own. It can only contribute a conservative "merged"
+input, which the existing in-use/clean/blast-radius/breaker gates still sit in front of.
+
+## 5. Interactions
+
+- **`isClean` ordering:** unchanged — `isMerged` (now with the gh path) is still only
+  reached AFTER the cheap protect-gates (in-use, dirty) clear, so no extra gh calls on
+  dirty/active worktrees.
+- **Caching:** 60s TTL map + the existing 10s cwd cache — one sweep = one gh call.
+- **Blast radius:** unchanged `maxReapsPerPass` (default 20) still caps deletions/sweep.
+- **Breaker:** unchanged per-path removal-failure breaker still applies.
+
+## 6. External surfaces
+
+- **New external call:** `gh pr list` (read-only) against the repo's GitHub. Requires gh
+  installed + authed; absent → fail-safe KEEP. No write, no new credential (uses the
+  ambient gh auth). Off-switch: `agentWorktreeReaper.githubMergeCheck: false`.
+- No new route, no user-facing message, no config migration required (the field defaults
+  true via `?? true`, so existing agents get the behavior on the dist update).
+
+## 7. Rollback
+
+Pure code + one config flag. `githubMergeCheck: false` restores cherry-only at runtime;
+reverting the commit removes the path entirely. The reaper's OFF+dry-run default means no
+agent reaps anything until explicitly enabled and reviewed.