instar 1.3.208 → 1.3.210

package/upgrades/1.3.210.md

@@ -0,0 +1,101 @@
+# 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`.
+
+`/metrics/features` now reports real per-feature token usage instead of always
+`tokensIn:0 / tokensOut:0`. Root cause (item 1 of the Iris-audit spec): the LLM
+funnel's metrics tap recorded latency/outcome/count but never had token data —
+`ClaudeCliIntelligenceProvider` ran `claude -p --output-format text`, which discards
+the `usage` block, and `IntelligenceProvider.evaluate()` returns only a string.
+
+The provider now runs `--output-format json`, parses the answer from `.result`, and
+surfaces token counts through a new additive optional `onUsage` callback on
+`IntelligenceOptions` — `evaluate()` still returns `Promise<string>`, so every existing
+caller is byte-identical. `CircuitBreakingIntelligenceProvider` (the universal LLM
+chokepoint) passes an `onUsage` that forwards `tokensIn/tokensOut` into the existing
+`FeatureMetricsLedger`, so per-feature token cost is now real. `tokensIn` sums the
+input components actually processed (fresh + cache-creation + cache-read); `tokensOut`
+is output tokens. Parsing is defensive — non-JSON or a missing `.result` falls back to
+the raw text, so a malformed response degrades to "answer without token accounting,"
+never a crash.
+
+## 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."
+
+- **The token cost screen works now.** "My per-feature cost view used to show 0 tokens
+  for everything even though my background checks clearly cost tokens — the number was
+  never being recorded. It now shows real token usage, so we can actually see which
+  checks are expensive and tune them."
+
+## 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`) |
+
+| Capability | How to Use |
+|-----------|-----------|
+| Real per-feature token usage | `GET /metrics/features` — `tokensIn` / `tokensOut` now populated |
+
+## 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).
+
+- **Root cause:** `ClaudeCliIntelligenceProvider` used `--output-format text` and the
+  `CircuitBreakingIntelligenceProvider` tap (`recordMetric`) passed no tokens, so
+  `FeatureMetricsLedger`'s token columns were always null → summed to 0.
+- **Live CLI shape verified:** `claude -p --model haiku --output-format json` returns
+  `{ result:"ok", usage:{ input_tokens:10, output_tokens:41, cache_*:… } }`.
+- **Tests:** `tests/unit/ClaudeCliIntelligenceProvider-jsonParse.test.ts` (parser
+  contract + defensive fallbacks) and `tests/unit/CircuitBreaking-feature-metrics-tap.
+  test.ts` (funnel forwards tokens; sums into the real ledger rollup, no longer 0).

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/iris-audit-token-accounting.md

@@ -0,0 +1,125 @@
+# Side-Effects Review — Iris-audit token usage accounting (PR B: item 1)
+
+**Version / slug:** `iris-audit-token-accounting`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Second-pass reviewer:** `convergence reviewers (shared spec) — concur`
+
+## Summary of the change
+
+PR B of the Iris-audit spec (`docs/specs/iris-audit-session-observability.md`), item
+1: make `/metrics/features` report real per-feature token usage instead of always 0.
+`ClaudeCliIntelligenceProvider` switches `claude -p` from `--output-format text` to
+`json` and parses the result object for the answer (`.result`) and `usage`; a new
+additive optional `onUsage` callback on `IntelligenceOptions` surfaces the token
+counts. `CircuitBreakingIntelligenceProvider` (the universal LLM funnel) passes an
+`onUsage` that captures usage and forwards `tokensIn/tokensOut` into the existing
+`FeatureMetricsLedger` tap. Files: `src/core/types.ts`, `src/core/
+ClaudeCliIntelligenceProvider.ts`, `src/core/CircuitBreakingIntelligenceProvider.ts`,
+plus tests. The decision points touched are observability-only — no gate changes.
+
+## Decision-point inventory
+
+- `IntelligenceOptions.onUsage` (types.ts) — **add** — optional callback; no decision
+  logic.
+- `ClaudeCliIntelligenceProvider.evaluate` output parsing (ClaudeCliIntelligence
+  Provider.ts) — **modify** — text→json + `parseJsonResult`; affects the return-value
+  extraction for EVERY Claude-backed LLM call, but the returned text is unchanged.
+- `CircuitBreakingIntelligenceProvider` metrics tap (CircuitBreakingIntelligence
+  Provider.ts) — **modify** — now forwards token counts; observability only.
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. This is pure observability
+plumbing; nothing is rejected.
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. (If usage is ever absent or
+unparseable, the only effect is that a call's token cost is omitted — recorded as the
+pre-existing 0/null — never a wrong block.)
+
+## 3. Level-of-abstraction fit
+
+Right layer. Token usage originates in the provider that runs the CLI
+(`ClaudeCliIntelligenceProvider`) — the only place it exists — and is surfaced via the
+same `IntelligenceOptions` contract every provider already takes. The funnel
+(`CircuitBreakingIntelligenceProvider`) is the established single chokepoint that
+already records the per-feature metric; threading tokens through it instruments ALL
+LLM features at once (Structure > Willpower) rather than each call site. The ledger is
+reused unchanged (it already had token columns waiting for data).
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [x] No — this change has no block/allow surface (it is observability: a signal
+  producer feeding the metrics ledger).
+
+The metrics ledger is a read-only signal surface (`/metrics/features`); it never gates.
+Token accounting strictly adds data; it holds no authority.
+
+## 5. Interactions
+
+- **Shadowing:** none — parsing happens inside `evaluate`'s existing resolve path; no
+  new check before/after another.
+- **Double-fire:** `onUsage` fires at most once per successful call (only when usage
+  is present with non-zero tokens); the funnel composes with (does not clobber) any
+  caller-supplied `onUsage`.
+- **Races:** none — synchronous parse within the call's own callback.
+- **Feedback loops:** none — recorded metrics are read-only; nothing consumes them to
+  re-drive an LLM call.
+
+## 6. External surfaces
+
+- **The claude CLI invocation changes** from `--output-format text` to `json`. This is
+  the load-bearing risk: the return value is now extracted from `.result`. Mitigation:
+  `parseJsonResult` is defensive — non-JSON or missing `.result` falls back to the raw
+  trimmed stdout (the prior behavior), so a malformed/partial response degrades to
+  "answer without token accounting," never a crash or a JSON blob leaking to callers.
+  The empirical CLI shape was verified live (`{ result, usage:{ input_tokens,
+  cache_creation_input_tokens, cache_read_input_tokens, output_tokens } }`).
+- **Rate-limit detection unaffected:** the circuit breaker's classifier reads
+  `stderr`, not stdout — the format switch does not touch it (verified in the provider;
+  the error path is unchanged).
+- **Other agents / install base:** ships fleet-wide via update; every LLM-backed
+  feature's calls now carry token counts into `/metrics/features`. No behavior change
+  to what those features decide — only the cost telemetry becomes real.
+- **Persistent state:** writes to the existing `FeatureMetricsLedger` SQLite token
+  columns (previously always null); no schema change (columns already existed).
+
+## 7. Rollback cost
+
+- **Hot-fix release:** pure code revert shipped as the next patch (revert the three
+  core files). No persistent-state migration — the ledger columns simply return to
+  null. No agent-state repair, no user-visible regression.
+- The only externally-observable change is `claude -p --output-format json`; reverting
+  restores `text`. Because `parseJsonResult` already tolerates non-JSON, even a partial
+  rollout (some agents on json, some on text) is safe.
+
+## Conclusion
+
+The review produced no design changes — the change is additive, observability-only, and
+defensively parsed. The single real risk (the CLI output-format switch) is contained by
+the raw-stdout fallback and verified against the live CLI shape. Clear to ship. This is
+the sibling of PR A under the same converged + approved spec.
+
+## Second-pass review (if required)
+
+**Reviewer:** the 3 spec convergence reviewers (shared spec) — concur on item 1's
+design (additive onUsage side-channel, no evaluate() return-type change). The one
+open question they raised — does onUsage fire on cache-only reads — is resolved here:
+`parseJsonResult` sums cache_read/cache_creation INTO tokensIn (they are real input
+cost) and fires whenever any count is non-zero, so cache-dominated calls are counted,
+not dropped.
+
+## Evidence pointers
+
+- `tests/unit/ClaudeCliIntelligenceProvider-jsonParse.test.ts` — parser contract
+  (extract .result, sum input components, defensive fallbacks, onUsage firing rules).
+- `tests/unit/CircuitBreaking-feature-metrics-tap.test.ts` — funnel forwards tokens to
+  the recorder, composes with caller onUsage, omits when absent, and sums into the real
+  ledger rollup (tokensIn/tokensOut no longer 0).
+- Live CLI shape verified: `claude -p --model haiku --output-format json` →
+  `{ result:"ok", usage:{ input_tokens:10, output_tokens:41, ... } }`.
+- `tsc --noEmit` clean.