instar 1.3.301 → 1.3.303

package/upgrades/side-effects/lifeline-replay-down-server-guard.md

@@ -0,0 +1,41 @@
+# Side-Effects Review — Lifeline replay drop budget: down-server exemption
+
+**Version / slug:** `lifeline-replay-down-server-guard`
+**Date:** `2026-06-05`
+**Author:** `instar-echo`
+
+## Summary
+
+In `TelegramLifeline.replayQueue()`, the failure branch's strike increment becomes healthy-gated: `msg.replayFailures = this.supervisor.healthy ? failures + 1 : failures`. A forward that fails while the supervisor reports the server DOWN re-queues the message with its strike count untouched. The drop decision itself (3 strikes → record + degradation report + sender notice) is unchanged.
+
+## Decision-point inventory
+
+- Replay strike increment — modified — gated on `this.supervisor.healthy` (the same flag the loop's own stop-replaying branch already consults three lines below; no new state).
+- Drop decision, versionSkewActive exemption, dropped-message notification, queue ordering — untouched.
+
+## Direction of failure
+
+- Old failure: systemic down-server failures burned the poison-message budget; head-of-queue messages dropped in ~90s of a multi-minute restart window (39 live records on codey).
+- New behavior: down-window failures are free; messages wait out the outage. Strikes only accrue against a healthy server.
+- Conservative failure direction: messages are KEPT longer. A genuinely poisonous message still accumulates strikes the moment the server is healthy (its delivery failure against a healthy server is precisely the poison signal) and is dropped with the existing loud path.
+
+## Side-effects checklist
+
+1. **Over-keep (message retained that should drop):** a poison message during an outage survives the outage — correct: it then fails 3x against the HEALTHY server and drops via the existing path. Worst case it delays its own drop by the outage length.
+2. **Under-keep:** none introduced — no path drops earlier than before.
+3. **Stale-healthy edge:** the supervisor may not yet have noticed a fresh crash, so the first failure after a crash can still increment. Acceptable: the budget is 3 and the guard's job is stopping the systematic burn across a known-down window; the loop's own `!supervisor.healthy` break uses the same flag with the same staleness, keeping the two behaviors consistent.
+4. **Queue growth:** an extended outage retains messages it previously shredded. Bounded by the queue's existing capacity controls; the alternative (dropping user messages) is the bug.
+5. **Level-of-abstraction fit:** policy stays inside `replayQueue()` next to the drop decision and the sibling versionSkewActive exemption — one drop policy, one place. No new flags, fields, or config.
+6. **Signal vs authority:** no LLM; the drop path's loud notification chain is preserved verbatim.
+7. **Rollback cost:** revert the one-line gate (plus comment + tests). No state migration; dropped-messages.json shape unchanged.
+
+## Scope not taken
+
+- No change to MAX_REPLAY_FAILURES (3 remains right for the poison case).
+- No fix for the separate `telegram-forward sentinel pause` limbo (held-not-dropped message on an idle session; ledger issue 38edd8f0, distinct mechanism on the SERVER side — this fix is the LIFELINE side).
+- No retroactive redelivery of already-dropped messages (the ledger + sender notices already cover them).
+- SlackLifeline has its own replay path — audit as a follow-up, not blind-patched here.
+
+## Rollback
+
+Revert the commit. Behavior returns to unconditional strike increments.

package/upgrades/side-effects/mentor-tick-observability.md

@@ -0,0 +1,44 @@
+# Side-Effects Review — Mentor tick observability (durable lastResult + tick logging)
+
+**Version / slug:** `mentor-tick-observability`
+**Date:** `2026-06-05`
+**Author:** `instar-echo`
+
+## Summary
+
+`MentorRunnerServices` gains optional `loadLastResult`/`saveLastResult`; the runner hydrates `lastResult` once at construction and routes all three write paths (disabled short-circuit, success, failure) through one `setLastResult` funnel that persists best-effort. The host (`AgentServer.buildMentorRunner`) wires both to `<stateDir>/mentor-last-result.json` (atomic tmp+rename write; shape-checked, corrupt-tolerant load). `startTick` logs one line on acceptance and one on outcome.
+
+## Decision-point inventory
+
+- `MentorRunnerServices.loadLastResult` / `saveLastResult` — added — optional; absent ⇒ byte-for-byte old behavior (in-memory only).
+- `MentorOnboardingRunner.setLastResult` — added — single write funnel; persist failures contained (in-memory value already set).
+- Constructor hydration — added — try/catch contained; corrupt/missing ⇒ null (old start state).
+- `startTick` logging — added — two `console.log` lines per accepted tick; no logging change on the disabled/in-flight short-circuits (they stay quiet — they fire every 15 min when dark and would be log spam).
+- `AgentServer.buildMentorRunner` — modified — wires the two services only when `stateDir` exists; the persist file lives beside the existing `mentor-sent.jsonl` precedent.
+
+## Direction of failure
+
+- Old failure: the loop's only outcome record was wiped by every restart; success was silent in logs — "is the mentor alive?" was unanswerable from its own surfaces.
+- New behavior: outcome survives restarts; the log carries the loop's pulse.
+- Conservative failure direction: ALL new I/O is best-effort and contained — a missing stateDir, unreadable file, corrupt JSON, or full disk degrades to exactly the old in-memory behavior, never a crash, never a blocked tick.
+
+## Side-effects checklist
+
+1. **Over-block:** none possible — the change never gates or refuses anything; it records and logs only.
+2. **Under-block:** none — no authority added. A stale persisted lastResult after config flip-off is possible (file shows an old outcome while disabled writes overwrite it on the next tick POST) — acceptable: the disabled short-circuit itself writes `reason: disabled`, refreshing the file on the very next heartbeat.
+3. **Level-of-abstraction fit:** the runner owns WHEN to persist (its write funnel); the host owns WHERE/HOW (state-dir path + atomic write) — mirrors the existing `capture`/`deliverToMentee` service split and the `mentor-sent.jsonl` persistence precedent.
+4. **Signal vs authority compliance:** observability-only; no LLM, no gate. Log lines are signals.
+5. **Interactions:** the persisted shape is exactly the in-memory `MentorRunResult & { at }` — the status route serializes it identically whether hydrated or fresh. The hydrated value can briefly present a PRIOR generation's outcome after a restart until the next tick overwrites it — that is the feature (it is timestamped via `at`, so staleness is readable).
+6. **External surfaces:** GET /mentor/status semantics unchanged (same field, now durable). One new state file in the agent state dir. Two new log line shapes (`[mentor] tick accepted…` / `[mentor] tick result…`).
+7. **Rollback cost:** revert the commit; the state file is ignored by old code (no reader), safe to leave or delete.
+
+## Scope not taken
+
+- No fix for the job-session 1-min age-limit race (`expectedDurationMinutes: 1` vs heavy boot) — that is task #14's lean loop-worker territory; this slice makes the symptom DIAGNOSABLE first.
+- No X-Instar-AgentId header fix in the job template (auth deprecation warning) — separate small follow-up.
+- No grounding-config addition for the mentor job (JobLoader audit warning) — separate.
+- No change to tick cadence, gating, budget, or Stage-A/B behavior.
+
+## Rollback
+
+Revert the single commit. The runner returns to in-memory-only lastResult and silent successful ticks.