instar 1.3.558 → 1.3.560

package/upgrades/1.3.559.md

@@ -0,0 +1,48 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Reap notices no longer dress a routine **session recycle** up as a death. A long
+autonomous run periodically hits its per-session lifetime cap, at which point the
+old terminal process is replaced by a fresh one that continues the run — but the
+user used to see `🪦 Your session was shut down — it reached its maximum allowed
+runtime`, even while the run's own clock still showed many hours remaining. Now,
+when an `age-limit` reap targets a session whose topic has an ACTIVE autonomous
+run, ReapNotifier emits honest continuation copy instead:
+`🔄 Your session was recycled at its per-session lifetime cap — your autonomous
+run has 11h 42m left, so no work was lost. I'll pick it back up on my next turn —
+send a message if I stay quiet.`
+
+It never goes silent: any read error, or a run that is genuinely over, falls back
+to the normal loud "shut down" notice. Only the age-limit-recycle-of-an-active-run
+case is reworded; a stuck-session death is still surfaced loudly even mid-run.
+
+## What to Tell Your User
+
+If you run long autonomous sessions and were alarmed by repeated "your session was
+shut down — reached its maximum allowed runtime" messages: those were usually a
+routine recycle, not a failure — your work was never lost and the run kept going.
+You'll now see an honest "🔄 recycled, your run has Xh left, no work lost" notice
+for that case instead of the tombstone. A genuine stop still shows the loud notice.
+
+## Summary of New Capabilities
+
+- Honest reap-notice wording for an age-limit recycle of a still-active autonomous
+  run (continuation, not death), with the run's real remaining time.
+- New shared helper `autonomousRunRemainingForTopic` (one source of truth for "is
+  this topic's run in-flight, and how long is left?").
+
+## Evidence
+
+- `tests/unit/reap-notifier.test.ts` — honest-recycle block: recycle copy,
+  never-contradicts-clock, no-run→death, only-age-limit, throws→fail-loud,
+  over-window→death.
+- `tests/unit/AutonomousSessions.test.ts` — `autonomousRunRemainingForTopic`:
+  in-flight remaining, numeric/string topic, over-window null, no-run/paused/
+  missing-duration null.
+- `tests/integration/honest-session-recycle-wiring.test.ts` — real helper composed
+  with real notifier (dep non-null, real computed remaining).
+- `npx tsc --noEmit` clean; 51/51 unit + 2/2 integration green.

package/upgrades/1.3.560.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+PR #1155 fixed the misleading NOTICE for an age-limit recycle of an active
+autonomous run ("recycled, no work lost, I'll pick it back up on my next turn").
+This change closes the behavioral gap behind that notice: the run now actually
+comes back on its own, instead of waiting for the next message.
+
+A long autonomous run periodically hits its per-session lifetime cap and gets
+recycled. That age-limit reap fires precisely when the session is IDLE between
+turns — so the Mid-Work Resume Queue saw no in-flight work evidence and never
+queued the run for revival. If the operator was away, the run sat dead until they
+sent a message. Now, when an age-limit reap targets a topic that still has an
+ACTIVE autonomous run, the live run itself counts as the work evidence: the reap
+is admitted to the resume queue and revived through the SAME one-at-a-time,
+quota-gated, resurrection-capped machinery as any other revival.
+
+It stays safe by construction: a double-spawn is caught by the existing
+live-session / resume-uuid drain-time checks (a message-revive that beat the queue
+wins, ZERO second spawn); a run that keeps getting reaped-and-revived hits the
+resurrection cap and gives up loudly with one aggregated notice; a run that has
+since finished (or whose window elapsed) is invalidated at drain time, never
+re-spawned. The resume queue runs LIVE on a development agent and stays
+observe-only on the fleet.
+
+## What to Tell Your User
+
+If you kick off a long autonomous run and walk away: when the session hits its
+per-session lifetime cap and gets recycled, the run now revives itself
+automatically instead of sitting idle until you next message it. You no longer
+have to send a "you still there?" nudge to wake a recycled run back up. Nothing
+double-runs, and a run that has genuinely finished is left alone.
+
+## Summary of New Capabilities
+
+- An age-limit recycle of a topic with an active autonomous run is now admitted to
+  the Mid-Work Resume Queue and auto-revived (the live run is the evidence).
+- A drain-time liveness re-check invalidates an entry whose run finished or whose
+  window elapsed between enqueue and drain (never a wasted respawn).
+- The resume queue resolves live-on-dev (dryRun:false) / observe-only-on-fleet,
+  with an explicit operator override still winning.
+
+## Evidence
+
+- `tests/unit/resume-idle-autonomous.test.ts` — admission both sides, guard
+  short-circuit (non-age-limit / null-topic / fail-open), dryRun-gate resolution
+  (dev/fleet/explicit), drain-time re-check both sides + back-compat + throwing-dep.
+- `tests/integration/resume-idle-autonomous-wiring.test.ts` — real-helper
+  delegation, double-spawn lens (live-session + uuid-stale), lease lens,
+  revival-loop lens (resurrection cap fires exactly once).
+- `tests/e2e/resume-idle-autonomous-lifecycle.test.ts` — feature alive on dev
+  (dryRun:false), enters-and-revives-once + no double spawn, fleet observe-only.
+- `npx tsc --noEmit` clean; lint clean; docs-coverage check passed.

package/upgrades/side-effects/honest-session-recycle.md

@@ -0,0 +1,140 @@
+# Side-Effects Review — Honest Session Recycle
+
+**Version / slug:** `honest-session-recycle`
+**Date:** `2026-06-14`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `independent reviewer subagent — CONCUR (2 non-blocking concerns, both resolved)`
+
+## Summary of the change
+
+When a session is reaped at its per-session lifetime cap (`reason: 'age-limit'`)
+but its Telegram topic still has an ACTIVE autonomous run, the recycle is a
+continuation (the run respawns), not a death. ReapNotifier now stamps that fact
+at ingest and emits honest "🔄 recycled at its lifetime cap — your autonomous run
+has Xh left, resuming; no work was lost" copy instead of the false "🪦 reached its
+maximum allowed runtime" gravestone. Files: `src/monitoring/ReapNotifier.ts`
+(new optional dep `autonomousRunActiveFor`, ingest stamp, four render branches,
+two pure helpers), `src/commands/server.ts` (wires the dep via a new
+`autonomousRunRemainingForTopic`), `src/core/AutonomousSessions.ts` (the extracted
+run-remaining helper). No SessionManager / kill-chokepoint change.
+
+## Decision-point inventory
+
+- `ReapNotifier.onReaped` ingest — **modify** — stamps `autonomousRunActive` when
+  an `age-limit` reap has an active run; affects only NOTICE WORDING, never
+  whether a notice is sent.
+- `ReapNotifier` render (single/aggregate/unbound/legacy) — **modify** — branch the
+  per-event copy on the stamp.
+- The reap/respawn behavior itself — **pass-through** — unchanged.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — this change only chooses notice WORDING. It can never
+suppress a notice: the only effect of the recycle branch is gentler copy; the
+notice is always still sent. Over-block not applicable.
+
+## 2. Under-block
+
+No block/allow surface. The nearest analogue is "could a real death be softened
+into a recycle?" — covered: the stamp requires `reason === 'age-limit'` AND an
+active run with remaining > 0. A stuck-session death (`idle-zombie`,
+`watchdog-stuck`, etc.) is never softened even mid-run (unit-tested). A run past
+its window returns null → death copy stands.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. The wording decision lives in ReapNotifier (the existing single
+listener that already owns "is this a disappearance worth a notice?"). The
+autonomous-state lookup lives at the server wiring layer (which has the state) and
+is computed by one shared helper `autonomousRunRemainingForTopic` in
+AutonomousSessions.ts — the same module that owns the run-window data — so the
+recycle copy and any future caller agree on "is this run in-flight, how long
+left?". SessionManager's kill chokepoint is deliberately NOT touched (lowest blast
+radius).
+
+## 4. Signal vs authority compliance
+
+**Reference:** docs/signal-vs-authority.md
+
+- [x] No — this change has no block/allow surface. It is pure presentation: a
+  signal (the autonomous-run fact) consumed to choose honest wording. It holds no
+  authority over reaping, respawning, or whether a notice fires. Fails toward the
+  loud legacy copy on any error.
+
+## 5. Interactions
+
+- **Shadowing:** none — the branch is inside the existing notice formatter; it
+  does not run before/after any other check.
+- **Double-fire:** none — still exactly one `sessionReaped` → one notice per the
+  existing coalescing; this only changes the text.
+- **Races:** the autonomous-run state is read at INGEST (synchronously when the
+  event arrives), not at the SUMMARY release (which can be ~30 min later), so the
+  "X left" figure reflects reap time and can't drift to a stale/negative value at
+  render. The reported `remainingSeconds` is a point-in-time snapshot, by design.
+- **Feedback loops:** none — reads autonomous state, writes only notice text.
+
+## 6. External surfaces
+
+- Telegram: the user-visible reap notice text changes for the active-run recycle
+  case (🔄 + "no work was lost") — this is the intended fix. All other reap
+  notices are byte-identical.
+- No other-agent, GitHub, Cloudflare, or persistent-state surface. No new route.
+- **Operator surface (Mobile-Complete):** no operator-facing actions added — this
+  is an outbound notice wording change only. Not applicable.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable. No `dashboard/*` or approval/grant/secret
+form is touched.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** Reap notices are emitted by the machine that owns
+and reaps the session; the autonomous run state read (`config.stateDir`) is that
+same machine's. A recycle on machine A is narrated by machine A in the topic — the
+correct single voice for that event (the reaping machine is authoritative about
+its own reap). No durable state is created (notice text only), so nothing strands
+on topic transfer. No URLs generated. One-voice: the notice rides the existing
+ReapNotifier coalescing + reap-notice drain, which already own single-emission.
+
+## 8. Rollback cost
+
+Pure code change — revert the three files and ship a patch. No persistent state,
+no migration, no agent-state repair. During any rollback window the only
+regression is the notice reverting to the old (alarming-but-not-harmful) wording.
+No user data affected. The feature is also inert by construction when no
+autonomous run is active (the common case) — it only ever activates on an
+age-limit recycle of a live run.
+
+## Conclusion
+
+The review produced one design refinement during the build: the run-remaining
+computation was extracted from an inline server.ts block into a single tested
+helper (`autonomousRunRemainingForTopic`) so the run clock has one source of
+truth. The change is wording-only with a fail-loud default and full both-sides
+test coverage (recycle vs death; active / over-window / paused / no-run / missing
+duration / throws). Clear to ship pending the high-risk second-pass concurrence.
+
+## Second-pass review (if required)
+
+**Reviewer:** independent reviewer subagent (high-risk: reap-notifier / session-lifecycle)
+**Independent read of the artifact: CONCUR** (verified: fail-open is airtight across three layers; cannot silence a notice; terminal-death mislabeling is prevented by the `age-limit` + `remaining>0` guard; run-state read at ingest not render; pure presentation, no blocking authority).
+
+Two non-blocking concerns raised — **both resolved before commit:**
+
+- **Test-tier coverage.** Resolved: added `tests/integration/honest-session-recycle-wiring.test.ts`, which composes the REAL `autonomousRunRemainingForTopic` helper with the REAL ReapNotifier over a temp stateDir (the dep is non-null and delegates to the real run-window read) — the wiring-integrity tier. Tier-3 HTTP E2E is N/A by design: this change adds NO API route or feature-alive surface (it is outbound notice WORDING), so the canonical "feature returns 200" E2E does not apply; the integration composition is the appropriate top tier here.
+- **Copy over-promised self-resume.** Resolved: respawn is message-triggered today (spec F1), so the copy was corrected to "no work was lost. I'll pick it back up on my next turn — send a message if I stay quiet" (single) / "it resumes on its next turn" (legacy) — no "resumes automatically" claim.
+
+## Evidence pointers
+
+- `tests/unit/reap-notifier.test.ts` — honest-recycle describe block (6 tests):
+  recycle copy, never-contradicts-clock, no-run-death, only-age-limit, throws-fails-safe, over-window-death.
+- `tests/unit/AutonomousSessions.test.ts` — `autonomousRunRemainingForTopic`
+  describe block (4 tests): in-flight remaining, numeric/string topic, over-window
+  null, no-run/paused/missing-duration null.
+- `tests/integration/honest-session-recycle-wiring.test.ts` — real helper composed
+  with real notifier (2 tests): in-flight run → honest recycle copy with real
+  computed remaining; no run file → terminal death copy.
+- `npx tsc --noEmit` clean; 51/51 unit + 2/2 integration tests green.

package/upgrades/side-effects/resume-idle-autonomous-on-reap.md

@@ -0,0 +1,146 @@
+# Side-Effects Review — Resume an idle autonomous run after an age-limit reap
+
+**Slug:** `resume-idle-autonomous-on-reap`
+**Date:** `2026-06-14`
+**Author:** `echo`
+**Spec:** `docs/specs/resume-idle-autonomous-on-reap.md` (converged + approved)
+**ELI16 companion:** `docs/specs/resume-idle-autonomous-on-reap.eli16.md`
+**Second-pass reviewer:** required (this change makes the resume queue produce
+REAL respawns on a dev agent — a Guard/authority surface). Reviewer concurred.
+
+## Summary of the change
+
+The Mid-Work Resume Queue revives a reaped session only when the reap carried
+mid-work evidence. An **age-limit** reap fires precisely when an autonomous
+session is IDLE between turns (the idle gate requires an idle prompt + no
+non-baseline child processes), so its work evidence is empty by construction —
+and the run is never queued for revival. An away-operator's autonomous run then
+sits dead until the next inbound message.
+
+The fix: when an `age-limit` reap targets a topic that still has an ACTIVE
+autonomous run (`autonomousRunRemainingForTopic(stateDir, topicId) != null`),
+the `sessionReaped` wiring appends the TRUE `build-or-autonomous-active` strong
+signal to the candidate's evidence and tags the reason
+`age-limit (active autonomous run)`. The entry then flows through the EXISTING
+one-at-a-time, quota-gated, resurrection-capped, lease-gated machinery — no new
+respawn path. A drain-time liveness re-check invalidates the entry
+(`autonomous-run-finished`, never a spawn) if the run finished or its window
+elapsed between enqueue and drain. The resume queue resolves **live-on-dev**
+(`dryRun:false`) and stays observe-only on the fleet.
+
+Files touched:
+
+- `src/core/WorkEvidence.ts` — new exported constant
+  `AGE_LIMIT_ACTIVE_RUN_REASON = 'age-limit (active autonomous run)'` (the
+  evidence-vocabulary home; imported by server.ts + ResumeQueueDrainer.ts).
+- `src/commands/server.ts` —
+  (1) the resume-queue `dryRun` config resolves
+  `rqCfg.dryRun ?? !resolveDevAgentGate(undefined, config)` (live-on-dev) at the
+  single consumption site (config + boot log line);
+  (2) the `sessionReaped` candidate construction appends
+  `build-or-autonomous-active` + the reason tag when `reason === 'age-limit'` &&
+  `topicId != null` && `autonomousRunRemainingForTopic(...) != null` (inside the
+  existing enqueue try/catch);
+  (3) the ResumeQueueDrainer deps gain `autonomousRunFinished: (topicId) =>
+  autonomousRunRemainingForTopic(config.stateDir, topicId) == null`.
+- `src/monitoring/ResumeQueueDrainer.ts` — new OPTIONAL injected dep
+  `autonomousRunFinished?: (topicId, reason) => boolean` + a `validateReality`
+  re-check that returns `autonomous-run-finished` for an entry tagged with the
+  age-limit-active-run reason whose run is no longer active. Absent dep ⇒ today's
+  behavior (back-compat).
+- `tests/unit/resume-idle-autonomous.test.ts` — new (15 tests): admission both
+  sides, guard short-circuit, fail-open, dryRun-gate resolution (dev/fleet/explicit),
+  drain-time re-check both sides + back-compat + throwing-dep.
+- `tests/integration/resume-idle-autonomous-wiring.test.ts` — new (8 tests):
+  wiring integrity (real helper delegation), double-spawn lens (live-session +
+  uuid-stale), lease lens, revival-loop lens (resurrection cap fires once).
+- `tests/e2e/resume-idle-autonomous-lifecycle.test.ts` — new (4 tests): feature
+  is alive on dev (dryRun:false through the real AgentServer), enters-and-revives-
+  once + no double spawn, fleet observe-only (dryRun:true, would-resume, no spawn).
+
+## Decision-point inventory
+
+- **`sessionReaped` candidate construction (server.ts)** — **modify** — the
+  wiring layer that OFFERS a reap to the queue. The fix adds a TRUE evidence
+  signal at a SECOND origination site DOWNSTREAM of the SessionManager chokepoint;
+  `considerEnqueue` re-clamps via `clampWorkEvidence` and the token is a valid
+  `STRONG_WORK_EVIDENCE` member, so the enum invariant holds. Authority unchanged:
+  the queue's eligibility/cap/lease gates still decide.
+- **`ResumeQueueDrainer.validateReality`** — **modify** — adds one reality check
+  (a detector). Strictly additive: it can only ADD an invalidation, never wrongly
+  drop a legitimate revival (a throwing/absent dep resolves to NOT-finished, the
+  SAFE side).
+- **resume-queue `dryRun` resolution** — **modify** — flips the queue from
+  observe-only to LIVE on a dev agent. This is the authority change (real respawns
+  + real quota spend on Echo). An explicit operator `monitoring.resumeQueue.dryRun`
+  still wins; the keys stay CODE-defaulted (no ConfigDefaults write) so the fleet
+  flip is preserved.
+- **`AGE_LIMIT_ACTIVE_RUN_REASON`** — **new** — a code-internal string constant;
+  no external/published surface; reversible by changing one string.
+
+---
+
+## 1. Over-block (a gate refuses legitimate work)
+
+The drain-time re-check can only ADD an `autonomous-run-finished` invalidation,
+and only for an entry whose run genuinely returned `null` (completed or window
+elapsed) — exactly the case the spec wants NOT revived. A throwing/absent
+`autonomousRunFinished` resolves to NOT-finished, so a transient state-read error
+never blocks a legitimate revival. No over-block on the kill path: the augmentation
+sits inside the existing enqueue try/catch and a throw fails toward no-injection
+(status-quo no-revive), never toward endangering the reap.
+
+## 2. Under-block (a gate lets through what it should stop)
+
+Double-spawn is the #1 lens: an age-limit entry is an ordinary topic-bound entry
+once admitted, so `validateReality`'s `live-session-exists` + `resume-uuid-stale`
+catches catch a message-revive that happened between enqueue and drain (named
+tests in the integration tier — both ZERO respawn). The resurrection cap reads
+`tombstoneFor(stableKey)` (derived purely from topicId), never `workEvidence`, so
+the injected evidence CANNOT reset or evade the cap (named test). Only the literal
+`age-limit` reason is augmented — watchdog-stuck/idle-zombie/context-wedge/AUP-wedge
+and moved-topic reaps stay excluded.
+
+## 3. Reversibility
+
+`dryRun` flips back to observe-only by setting `monitoring.resumeQueue.dryRun: true`
+(or via the fleet default). The reason tag + evidence injection is a one-string +
+one-evidence-name change. The drainer dep is OPTIONAL — removing it restores prior
+behavior. NOTE: flipping `dryRun` back does NOT un-spend quota already burned by a
+respawn that already fired — see Frontloaded Decision D1 (classified NON-cheap,
+accepted under the named live phase).
+
+## 4. Blast radius / interactions
+
+The augmentation runs ONLY on `age-limit` reaps (the cold-path
+`autonomousRunRemainingForTopic` read is behind the `reason === 'age-limit'`
+short-circuit), so every other reap pays zero added cost. It reads the LOCAL
+autonomous-run state file (same vantage that admitted the entry). Coupling risk
+(D2): if a future maintainer narrows `build-or-autonomous-active` to mean strictly
+"a live child build process", this reuse silently breaks — flagged here.
+
+## 5. Multi-machine (Phase-C) posture
+
+Machine-local by design: the resume queue is per-machine (single-writer lock), the
+age-limit reap is observed on the machine the session ran on, and only the
+lease-holder drains it (`validateReality` returns `topic-owner-elsewhere` otherwise
+— named test). A run MOVED to another machine reaches the queue as `topic moved …`
+(already `eligible:false`), not `age-limit`, so it is never double-revived.
+
+## 6. Migration parity
+
+NONE required — and that is correct. The `dryRun` resolution is a CODE default read
+at server boot, not a persisted `.instar/config.json` field, so existing agents pick
+it up on their next restart after update. A `migrateConfig` entry would freeze
+`dryRun` to disk and break the later fleet flip — the resume-queue keys must stay
+un-frozen in ConfigDefaults. No CLAUDE.md template change (internal plumbing, no new
+route or user-facing capability).
+
+## 7. Signal vs. authority
+
+The injected `build-or-autonomous-active` is a TRUE assertion about the world
+(the run is genuinely in-flight per the un-elapsed state file), supplied from the
+one vantage that can observe it — the opposite of lying to a classifier. The
+drain-time re-check is a detector that feeds the existing invalidation authority;
+it never spawns. The only authority change is the `dryRun` flip, which is bounded
+by the existing one-at-a-time / calm-ticks / quota / lease / resurrection-cap gates.