instar 1.3.207 → 1.3.209

package/upgrades/1.3.209.md

@@ -0,0 +1,66 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Three connected session-lifecycle fixes, all surfaced by a token-efficiency audit
+on a deployed agent:
+
+1. **The Claude session builder now honors the configured default model.**
+   `claudeCodeBuilder` resolved `frameworkDefaultModels['claude-code']` but never
+   passed `--model` to the `claude` CLI — unlike the Codex and Gemini builders,
+   which both do. So a configured default model was silently dropped for every
+   interactive Claude session; they always ran the CLI's account default. The
+   builder now pins `--model <resolved>` when a default is set (tier aliases
+   `fast|balanced|capable` → `haiku|sonnet|opus`; raw model ids pass through), and
+   pushes nothing when unset so the account default is preserved. This matches the
+   documented contract on `InteractiveLaunchOptions.defaultModel`.
+
+2. **`GET /sessions` now reports the real launched model for interactive sessions.**
+   The session record stores the model the session was *actually* launched with
+   (post Codex rate-limit swap), so after a config change you can confirm which
+   model a running session picked up.
+
+3. **New `POST /sessions/restart-all` bulk-restart endpoint.** A running session
+   keeps the config it was spawned with — and Claude Code loads hooks/settings only
+   at session start, so a newly-added hook never engages on a live session. There
+   was no way to push every session onto new config short of waiting for the reaper
+   or refreshing each by hand. `POST /sessions/restart-all` refreshes every running,
+   Telegram-bound session through the existing `SessionRefresh` path (kill +
+   `claude --resume`, each conversation preserved), staggered to avoid a respawn
+   storm. Pass `{"excludeSession":"<tmux-name>"}` to keep the caller alive;
+   non-Telegram-bound sessions are skipped and reported in `skipped`.
+
+## What to Tell Your User
+
+- **Your configured default model now actually applies to Claude sessions.** "If
+  you set a default model, my Claude sessions will launch with it now — previously
+  that setting was quietly ignored for Claude and only worked for Codex/Gemini."
+- **One command to apply a config or hook change to everything running.** "After
+  you change my default model, disable a feature, or add a hook, I don't pick it up
+  on a session that's already running — Claude only loads settings when a session
+  starts. I can now restart all my live sessions in one go (each conversation is
+  preserved) so the new config takes effect, then confirm what each one is running."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Configured default model applies to Claude sessions | Automatic (set `frameworkDefaultModels['claude-code']`) |
+| Per-session launched model in `GET /sessions` | `GET /sessions` → each session's `model` field |
+| Bulk restart all running sessions onto new config | `POST /sessions/restart-all` (one session: `POST /sessions/refresh`) |
+
+## Evidence
+
+- **Root cause (model):** `src/core/frameworkSessionLaunch.ts` `claudeCodeBuilder`
+  built `[binary, --dangerously-skip-permissions, (--resume id)]` with no `--model`,
+  while `codexCliBuilder`/`geminiBuilder` both push `--model`. Unit-proven in
+  `tests/unit/frameworkSessionLaunch.test.ts` (now asserts `--model` present when a
+  default is set, absent when unset, tier→model and raw-id pass-through).
+- **`restart-all`:** `tests/unit/sessions-restart-all-route.test.ts` drives the real
+  Express route — validation, 202 ack with honest `scheduled`/`skipped`, exclusion,
+  and that each target is refreshed through `SessionRefresh` after the stagger.
+- **Migration parity:** `tests/unit/PostUpdateMigrator-applyConfigToRunningSessions.test.ts`
+  proves existing agents get the awareness section on update (idempotent).

package/upgrades/side-effects/iris-audit-session-lifecycle.md

@@ -0,0 +1,146 @@
+# Side-Effects Review — Iris-audit session lifecycle (PR A: items 2/3/4)
+
+**Version / slug:** `iris-audit-session-lifecycle`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Second-pass reviewer:** `3 independent spec reviewers (convergence round) — concur`
+
+## Summary of the change
+
+PR A of the Iris-audit spec (`docs/specs/iris-audit-session-observability.md`),
+covering items 2/3/4. Three changes: (a) `claudeCodeBuilder` now pushes `--model
+<resolved>` when `frameworkDefaultModels['claude-code']` is set (it was silently
+dropped before — only Codex/Gemini builders passed it), and the interactive `Session`
+record stores the model actually launched with; (b) a new `POST /sessions/restart-all`
+route that bulk-refreshes every running Telegram-bound session through the existing
+`SessionRefresh` path (staggered, conversation-preserving); (c) a CLAUDE.md template
+section + idempotent `migrateClaudeMd` backfill teaching that hooks/config load at
+session start so applying a change requires a restart. Files: `src/core/
+frameworkSessionLaunch.ts`, `src/core/SessionManager.ts`, `src/server/routes.ts`,
+`src/scaffold/templates.ts`, `src/core/PostUpdateMigrator.ts`, plus tests and an
+upgrade fragment. Decision points touched: the interactive launch-arg builder
+(launch-shape, no block surface), the new restart-all action endpoint (real blast
+radius — reuses the existing rate-guarded `SessionRefresh` authority), and an
+additive idempotent doc migration.
+
+## Decision-point inventory
+
+- `claudeCodeBuilder` argv (frameworkSessionLaunch.ts) — **modify** — adds `--model`
+  when a default is set; pass-through otherwise. No block/allow surface.
+- `POST /sessions/restart-all` (routes.ts) — **add** — new action endpoint; delegates
+  to the existing `SessionRefresh` (does not add a new blocking authority).
+- interactive `Session.model` recording (SessionManager.ts) — **modify** — stores the
+  effective launched model; observational, no decision logic.
+- `migrateClaudeMd` awareness section (PostUpdateMigrator.ts) — **add** — additive,
+  idempotent, content-sniffed text backfill; no decision logic.
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The only gating is the existing
+`SessionRefresh` rate-guard (5/10min per session), reused unchanged; restart-all does
+not add or alter any allow/deny logic. The Telegram-bound filter is an inclusion
+filter (which sessions are eligible), not a rejection of legitimate input.
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. restart-all intentionally skips
+non-Telegram-bound sessions (Slack/iMessage/headless) — reported transparently in the
+`skipped` count, not silently dropped.
+
+## 3. Level-of-abstraction fit
+
+restart-all sits at the right layer: it is a thin HTTP route that orchestrates the
+existing, fully-tested `SessionRefresh` orchestrator (which owns kill+respawn,
+rate-guarding, in-flight protection, and topic resolution). It does NOT re-implement
+any of that — it loops the existing primitive with a stagger. The model-launch change
+is at the builder layer where every other framework already applies `--model`. The
+awareness change is documentation, delivered via the established `migrateClaudeMd`
+mechanism. Nothing is at the wrong layer; no parallel re-implementation of an existing
+primitive.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [x] No — this change has no block/allow surface (restart-all reuses the existing
+  `SessionRefresh` authority; the model record and the awareness section are signals/
+  documentation).
+
+The model field on `GET /sessions` is a pure signal (observability). restart-all
+carries the authority to kill+respawn, but that authority already exists in
+`SessionRefresh` (used by `/sessions/refresh`); this change does not create a new
+brittle authority — it reuses the smart, rate-guarded one. No brittle detector owns
+blocking authority here.
+
+## 5. Interactions
+
+- **Shadowing:** restart-all runs N independent single-refreshes; it neither shadows
+  nor is shadowed by other `/sessions/*` routes (it only reads the session list and
+  calls `SessionRefresh`).
+- **Double-fire:** the in-flight guard inside `SessionRefresh` prevents a second
+  refresh of the same session firing before the first completes, so restart-all can't
+  double-restart a session even if called twice.
+- **Races:** the target set is snapshot-time; a session spawned after the snapshot is
+  untouched (documented). The reaper interaction is NOT new — restart-all reuses the
+  exact shipped `/sessions/refresh` path; a freshly respawned session has current
+  activity (not idle-reapable) and the old session is marked `killed`.
+- **Feedback loops:** none. restart-all is a one-shot operation; it does not feed a
+  system that re-triggers it.
+
+## 6. External surfaces
+
+- **Other agents on the machine:** none — restart-all only acts on THIS agent's own
+  sessions (its own `state`/`SessionRefresh`).
+- **Install base:** items 2 and 4 reach the fleet via update. Item 2 makes a
+  previously-inert config (`frameworkDefaultModels['claude-code']`) active — effect
+  appears only on a fresh session, only when the field is set, and is auditable via
+  `GET /sessions` (documented "activation safety"). Item 4 appends an idempotent
+  CLAUDE.md section.
+- **External systems:** Telegram only insofar as restarted sessions resume their
+  Telegram-bound conversations via `claude --resume` — same as the existing single
+  refresh.
+- **Persistent state:** the `Session` record now carries `model` for interactive
+  sessions (additive field); no schema migration needed (optional field already on the
+  `Session` type). The CLAUDE.md migration appends text idempotently.
+- **Timing:** the restart-all stagger (500 + i·750 ms) spreads respawns; no fleet-wide
+  concurrency ceiling in v1 (per-session rate-guard is the aggregate backstop; named
+  as a known bound in the spec).
+
+## 7. Rollback cost
+
+- **Hot-fix release:** pure code revert shipped as the next patch.
+- **Data migration:** none — `Session.model` is an optional field already in the type;
+  reverting just stops populating it for interactive sessions.
+- **Agent state repair:** none. The CLAUDE.md migration is idempotent and additive;
+  reverting the migrator leaves already-patched CLAUDE.md files harmlessly carrying the
+  section (no removal needed).
+- **User visibility:** no user-visible regression during the rollback window. Item 2's
+  effect only manifests on a fresh session; reverting simply returns Claude sessions to
+  the CLI account default.
+
+## Conclusion
+
+The review produced no design changes to PR A's code — the changes are additive and
+reuse existing authorities. The convergence round refined the SPEC's documentation
+(snapshot semantics, fleet bound, reaper-reuse, activation safety, idempotency
+pattern). Clear to ship. Item 1 (token accounting) ships as the sibling PR B against
+the same spec.
+
+## Second-pass review (if required)
+
+**Reviewer:** 3 independent spec reviewers (design-correctness, safety/blast-radius,
+completeness/standards-fit)
+**Independent read of the artifact: concur**
+
+All three reviewers' material findings were resolved in-spec; the two "item 1 not
+implemented" criticals were a misunderstanding of the intended PR A / PR B phasing
+(item 1 is PR B, tracked via `deferrals-tracked`). No structural redesign. See
+`docs/specs/reports/iris-audit-session-observability-convergence.md`.
+
+## Evidence pointers
+
+- `tests/unit/frameworkSessionLaunch.test.ts` — `--model` set/unset/tier/raw/with-resume.
+- `tests/unit/sessions-restart-all-route.test.ts` — real Express route behavior.
+- `tests/unit/PostUpdateMigrator-applyConfigToRunningSessions.test.ts` — migration idempotency.
+- `tests/unit/feature-delivery-completeness.test.ts` — template↔migrator parity (green).
+- `tsc --noEmit` clean; `pnpm build` clean.

package/upgrades/side-effects/spinner-immune-liveness.md

@@ -0,0 +1,122 @@
+# Side-Effects Review — spinner-immune liveness signal
+
+**Version / slug:** `spinner-immune-liveness`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Second-pass reviewer:** `instar-codey (codex) — cross-model review completed; verdict incorporated`
+
+## Summary of the change
+
+`src/monitoring/sentinelWiring.ts`: `OutputActivityTracker.snapshot()` now hashes
+`stripVolatileStatus(output, framework)` instead of the raw pane. `stripVolatileStatus`
+strips the host's animated working-status region (Braille spinner glyphs, the
+`Nm Ns` / `(Ns` elapsed timers, token/context counters, and the `esc to interrupt`
+footer line) so only real scrollback changes refresh `lastChangeAt`. Fixes the
+silence sentinel being permanently blinded by the spinner's ticking clock.
+
+## Decision-point inventory
+
+- `OutputActivityTracker: did this frame change?` (sentinelWiring.ts:~215) — **modify**
+  — the hashed input is now spinner-normalized. The downstream "observed-change
+  requirement" + `looksActivelyWorking` + silence-threshold logic are unchanged.
+
+---
+
+## 1. Over-block
+
+**No block/allow surface — over-block not applicable.** The change cannot reject or
+block anything. The only effect is that the silence sentinel correctly recognizes a
+stalled-but-spinning turn as idle (rather than perpetually "active") and may issue
+its existing non-destructive `Enter` nudge.
+
+---
+
+## 2. Under-block
+
+**What does it still miss?** It strips a conservative, anchored set of volatile
+tokens; an exotic future spinner format could still leak a changing token into the
+hash (degrading gracefully back to the old "always active" behavior for that host —
+no worse than today). It does not change the silence THRESHOLD; a true stall is
+detected at the existing ~16-min mark.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer — a normalization at the change-detector's input boundary, reusing the
+existing per-framework `getActivitySignal` patterns rather than inventing new ones.
+It feeds the existing smart silence sentinel; it does not add a parallel detector or
+hold any authority.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change produces a signal (a fresher/stale activity timestamp)
+  consumed by the existing `ActiveWorkSilenceSentinel`, which owns the (non-destructive)
+  recovery decision.
+
+The cross-model review (Codey) specifically affirmed the signal-vs-authority shape:
+absence-of-activity must NOT authorize destructive recovery; here it only authorizes a
+non-destructive `Enter` nudge, and the destructive Ctrl-C path (SocketDisconnectSentinel)
+remains gated on a POSITIVE error-string marker. No change weakens that.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none — same single hash site; downstream logic unchanged.
+- **Double-fire:** none — `SocketDisconnectSentinel` (error-string → Ctrl-C) and
+  `ActiveWorkSilenceSentinel` (silence → Enter) remain independent; this only un-blinds
+  the latter.
+- **Races:** none — pure synchronous string transform inside the existing snapshot tick.
+- **Feedback loops:** the Enter nudge could, on a genuinely-long generation, submit a
+  stray blank line; the pane is mid-turn (spinner present) so it is queued/ignored, not
+  destructive. Verified the nudge is `sendKey(session, 'Enter')` (sentinelWiring.ts:255),
+  not Ctrl-C.
+
+---
+
+## 6. External surfaces
+
+- Persistent state: none.
+- External systems: none.
+- Behavior visible to operators: a stalled-but-spinning session now appears in
+  `logs/sentinel-events.jsonl` as detected/nudged where before it was invisible. The
+  Telegram escalation default (off) is unchanged.
+- Runtime: one extra string transform per session per silence tick — negligible.
+
+---
+
+## 7. Rollback cost
+
+Pure code change — revert `stripVolatileStatus` + restore `cheapHash(output)`, ship a
+patch. No persistent state, no migration, no user-visible regression (it would simply
+return to the prior "spinner fools the detector" behavior).
+
+---
+
+## Conclusion
+
+The cross-model review materially improved this change: it began as a multi-state
+process-activity gate to protect long generations from a *destructive* Ctrl-C, but the
+reviewer's grounded catch — the silence nudge is `Enter`-only, not Ctrl-C — collapsed it
+to a single safe normalization, with the destructive path already correctly gated on a
+positive error marker elsewhere. Clear to ship as a Tier-1 monitoring reliability fix.
+
+## Second-pass review (if required)
+
+**Reviewer:** instar-codey (codex)
+**Independent read: concur (after the implementation correction).** The reviewer's
+verdict drove the final design: do not let absence-of-activity authorize destructive
+recovery (already satisfied — the silence path is non-destructive `Enter`; Ctrl-C stays
+behind the SocketDisconnectSentinel error marker). No residual concern on the shipped
+shape.
+
+## Evidence pointers
+
+- `tests/unit/spinner-immune-liveness.test.ts` — 7 tests (normalizer + tracker behavior).
+- `src/monitoring/sentinelWiring.ts:255` — nudge is `sendKey(session, 'Enter')`.
+- Origin incident: `logs/server.log` + `logs/sentinel-events.jsonl`, 2026-06-02 26-min stall.