instar 1.3.66 → 1.3.68

package/upgrades/1.3.67.md

@@ -0,0 +1,164 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Fixed a runaway credit-burn bug: LLM call loops no longer keep hammering the
+provider after you hit a usage or spend limit.**
+
+Instar runs small background LLM calls to watch your sessions (for example, the
+per-tick check that detects when a session is blocked on a prompt). Until now,
+if one of those calls came back with a usage/rate/spend-limit error, the loop
+swallowed the error and tried again on the very next tick — with no backoff. If
+your account had auto-reload turned on, each retry refueled and re-burned. A
+real agent in the wild burned $452 of $455 in usage credits this way over a
+couple of days before anyone noticed.
+
+There is now an **account-global circuit breaker** in front of every internal
+LLM call. The moment the provider reports a usage/rate/spend limit, the breaker
+opens and *all* background LLM-backed work pauses — without spawning another
+`claude` subprocess, so it costs nothing while paused. After a cool-down window
+(15 minutes by default) it sends exactly one quiet probe; if the limit has
+lifted it closes and resumes automatically, and if not it waits another window.
+It is wired at the single provider-construction chokepoint, so every feature —
+current and future — is covered with no per-feature work.
+
+This is reactive (it listens to the provider's own "you're over limit" signal)
+and complements the existing volume-based burn-detection, which reacts to
+statistical token-share over a longer window.
+
+## What to Tell Your User
+
+Your agent can no longer burn through your credits by repeatedly calling the
+model after you've hit a usage or spend limit. The instant the provider says
+you're over your limit, background model work pauses on its own, costs nothing
+while paused, and quietly resumes once the limit lifts. This is on by default —
+no setup needed. If you ever want to tune the cool-down window or turn it off,
+there's an optional circuit-breaker setting in your config, but the safe
+defaults are designed to just work.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Account-global LLM rate-limit circuit breaker | Automatic. When the provider returns a usage/rate/spend-limit error, all background LLM-backed work pauses (no subprocess spawned) and self-heals via a single probe after the cool-down. |
+| Tunable cool-down / kill switch | Optional `intelligence.circuitBreaker` in `.instar/config.json`: `enabled` (default true) and `openMs` (default 900000 = 15 min). Absent config uses the safe defaults, so existing agents are protected with no changes. |
+
+## Evidence
+
+**Reproduction (the incident pattern), reproduced as an automated test:** a fake
+`claude` binary that records each spawn to an on-disk counter and exits with
+"Claude AI usage limit reached" on stderr.
+`tests/integration/llm-circuit-breaker-chokepoint.test.ts` builds two providers
+through the real `buildIntelligenceProvider` factory and drives them:
+
+- Before fix (old behaviour): every `evaluate()` call spawns the binary →
+  unbounded spawns while limited (this is exactly the $452 burn).
+- After fix (observed in the test): the first call spawns once and trips the
+  breaker; the next 5 calls — and a call through a *second, independently built*
+  provider — all reject with `LlmCircuitOpenError` and the spawn counter stays
+  at **1**. Zero additional subprocesses, proving the burn is stopped and the
+  breaker is account-global.
+
+39 new circuit-breaker tests pass (state machine both-sides-of-boundary, the
+rate-limit classifier on true-positive and unrelated-error strings, and the
+chokepoint wiring). `tsc --noEmit` clean. The server log emits
+`[llm-circuit] OPEN: …` / `[llm-circuit] closing: …` lines on each transition.
+
+---
+
+**Phase 2 of the unified session-lifecycle robustness work (spec
+`docs/specs/unified-session-lifecycle-robustness.md`).** The four remaining
+autonomous session killers — the SessionWatchdog, OrphanProcessReaper,
+SessionRecovery (kill-to-respawn), and the scheduler's wake-reaper — are now
+funneled through the single ReapAuthority that shipped in Phase 1. Each one
+gains the careful KEEP-checks and the awake-machine lease gate the previous
+killer-of-the-week didn't have, plus structural fixes to a few long-standing
+near-misses.
+
+What landed:
+
+- **#5 SessionWatchdog.** The final escalation level (the session-kill that
+  fires after Ctrl+C / SIGTERM / SIGKILL all failed to free a stuck child) now
+  routes through `terminateSession('watchdog-stuck', terminal/killed)` instead
+  of a raw `tmux kill-session`. If the authority's KEEP-guards refuse the kill
+  (a relay lease, an active subagent, a recent user message, etc.), the
+  watchdog STANDS DOWN — clears its escalation state, logs the exact refusal
+  reason, and lets the §P5 backstop own the operator-decision escalation.
+- **#6 OrphanProcessReaper.** Three changes. (a) Orphan classification is now
+  EXACT-id membership in `listKnownTmuxSessions()`, not project-prefix
+  startsWith — so a user-created `tmux new -s the-portal-myhand` is `external`,
+  not orphan, and the reaper cannot false-reap a user pane. (b) The 60-minute
+  age threshold is necessary, not sufficient: a new `processHasActiveChildren`
+  work-check (pgrep -P) vetoes the kill when the orphan still has running
+  children, and the deferred path logs a `Kept orphan PID … work check vetoed
+  reap` action. (c) When the orphan's tmux name matches a currently-tracked
+  session, the kill goes through the ReapAuthority for the lifecycle events +
+  reap-log entry.
+- **#8 SessionRecovery.** A single shared `killForRecovery()` helper consults
+  `hasActiveProcesses` before every kill-to-respawn — if the pane is producing
+  work, the JSONL stall/crash reading is unreliable and the recovery defers
+  with a structured `deferred-still-working` result. All four recovery paths
+  (stall, context-exhaustion, crash, error-loop) route through this helper.
+  The actual kill goes through `terminateSession('session-recovery',
+  recovery-bounce, bypassRecoveryFlag:true)` so the §P3 "shut down" notice
+  stays silent on a bounce (which is not a disappearance) and the reap-log
+  records the recovery-bounce disposition. `bypassRecoveryFlag` is narrowly
+  scoped to the `recovery-in-flight` KEEP-guard reason — all other KEEP-
+  guards still apply, so a session mid-conversation isn't killed-to-respawn
+  under the cover of "recovery."
+- **#9 wake-reaper.** Three changes. (a) The threshold-check now uses
+  CUMULATIVE wall-time-asleep during the run (the new
+  `SleepWakeDetector.getCumulativeSleepMsBetween()`), not the single last
+  `sleepDurationSeconds` event — a job that spanned multiple sleeps was
+  previously credited only the last sleep and reaped early. (b) The P1/P2 work
+  gate keeps a session whose process is still producing work, regardless of
+  clock. (c) The kill routes through `terminateSession('wake-reaper',
+  terminal/killed)` when tracked.
+
+All four killers now share the same brain — the structural guarantee the
+spec's audit named when it found "is this session alive/dead/stuck/working?"
+answered ad-hoc in eight different places.
+
+## What to Tell Your User
+
+- Every part of the agent that can shut a session down — the stuck-child
+  watchdog, the orphan-process cleanup, the crash-recovery, and the after-
+  sleep cleanup — now goes through the same careful gatekeeper that the boot
+  cleanup uses. None of them can quietly kill a session that might still be
+  working.
+- The watchdog's last-resort session kill, the crash-recovery's restart, and
+  the after-sleep cleanup all show up in the reap-log with the reason, so the
+  "where did my session go?" answer is always there.
+- A crash-recovery restart (kill + respawn fresh) stays quiet — it's a bounce,
+  not a disappearance — but it's still logged.
+- The orphan-process cleanup can no longer accidentally classify a tmux pane
+  you started yourself as one of mine, and it will defer the kill if the
+  orphan still has active child processes.
+- After your machine sleeps and wakes, the job cleanup correctly subtracts the
+  total sleep time (across multiple sleeps if needed) before deciding a job
+  ran too long, so a job that was paused while you closed the lid isn't
+  marked stuck.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Every autonomous killer routes through the single ReapAuthority | Automatic — the watchdog, orphan reaper, crash-recovery, and wake-reaper all funnel through `terminateSession`. |
+| Recovery-bounce disposition stays silent in the "shut down" notice | Automatic — a kill-to-respawn doesn't pretend a session vanished; it still lands in the reap-log. |
+| Orphan reaper: exact-id classification + work-check + ReapAuthority routing | Automatic — `listKnownTmuxSessions()` replaces the prefix match; `processHasActiveChildren` vetoes reaping a working orphan. |
+| Wake-reaper: cumulative-sleep math + P1/P2 work gate | Automatic — multi-sleep runs no longer reaped early; an actively-working session is kept regardless of clock. |
+
+## Evidence
+
+- All Phase 1 unit/integration/e2e tests remain green, plus 14 new Phase-2
+  wiring contracts (SessionWatchdog → ReapAuthority routing + KEEP stand-down,
+  OrphanProcessReaper exact-id + work-check + P0, SessionRecovery
+  killForRecovery + recovery-bounce + bypassRecoveryFlag scope, wake-reaper
+  cumulative-sleep + P1/P2 + P0), 6 new SleepWakeDetector cumulative-sleep
+  math tests, and the existing JobScheduler reaper suite (7) updated to the
+  new async + effective-elapsed contract.
+- `tsc --noEmit` clean. Existing SessionWatchdog (58), OrphanProcessReaper
+  (9), SessionRecovery (9), terminate-CAS (9), session-timeout/activity-aware
+  (4+6) tests all still pass.

package/upgrades/1.3.68.md

@@ -0,0 +1,71 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Phase 3 of the unified session-lifecycle robustness work (spec
+`docs/specs/unified-session-lifecycle-robustness.md`) — the last two items.**
+With Phase 1 and Phase 2 already on main, this completes the converged design:
+every autonomous killer shares the same brain, and the small UX bonus you
+asked for is in.
+
+What landed:
+
+- **#7 quota soft-check (bounded).** The quota-driven session migrator (the
+  thing that halts running sessions to switch accounts when you're running out
+  of weekly/5-hour budget) used to send Ctrl+C, wait `gracePeriodMs`, and then
+  force-kill anyone still alive. Now: when current usage is at or below a
+  configurable ceiling (`softCheckMaxUsagePercent`, default 95%), an
+  active build or autonomous run gets ONE extra Ctrl+C grace round before
+  force-kill. ABOVE the ceiling the soft check is **disabled** so quota's
+  final authority is never undermined; if current usage can't be read,
+  it's treated as 100% (fail-closed — no grace without proof we're below
+  the ceiling). The force-kill itself now goes through the single
+  ReapAuthority (`terminateSession('quota-shed', terminal/killed)`) so the
+  "your session was shut down" notice fires + the reap-log records the
+  `quota-shed` reason. A new structured `quota-force-kill-decision` event
+  publishes the inputs for a future Tier-1 supervisor.
+- **Bonus — session label follows topic rename.** When you rename a Telegram
+  forum topic, the bound session's display `name` updates to match. The
+  operational identity (`tmuxSession` key + `id` UUID) is never touched —
+  every internal lookup keeps working. The handler fires ONLY on a true
+  rename event (`forum_topic_edited`), not on initial-capture or topic
+  creation. The renamed value flows through the same §P3 sanitization
+  (literal code spans) wherever it surfaces in user-facing notices, so a
+  malicious name can't inject markup.
+
+This closes the spec's Phase 3 scope. After this, all eight autonomous
+killers (boot purge, age-kill, idle-zombie, watchdog, orphan reaper,
+SessionRecovery, wake-reaper, quota-shed) share the same authority + KEEP-
+guard + lease gate + reap-log + sessionReaped event.
+
+## What to Tell Your User
+
+- When you're running low on hours, the quota cleanup is gentler: a
+  session that's actively building or running an autonomous task gets one
+  more polite Ctrl+C before being shut down — unless we're already very
+  near the limit, in which case quota's final authority still kicks in
+  immediately. Either way, the shutdown shows up in the reap-log with the
+  reason.
+- When you rename a Telegram topic, the session label updates to match
+  what you renamed it. The agent's plumbing keeps working — only the
+  display name changes.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Bounded quota soft-check (one extra Ctrl+C grace for working sessions) | Automatic. Tunable via `monitoring.sessionMigration.thresholds.softCheckEnabled` / `softCheckMaxUsagePercent` (default 95) / `softCheckExtraGraceMs` (default = `gracePeriodMs`). |
+| Quota force-kill via ReapAuthority + `quota-force-kill-decision` event | Automatic — surfaces "your session was shut down — quota-shed" + lands in the reap-log; a future Tier-1 LLM supervisor can subscribe to the decision event. |
+| Session label follows Telegram topic rename | Automatic — rename a forum topic, the bound session's display name follows. |
+
+## Evidence
+
+- Unit: SessionManager rename (5) + Phase-3 wiring (9) green; SessionMigrator
+  existing (37) still passes; SessionWatchdog (58), OrphanProcessReaper (9),
+  SessionRecovery (9), terminate-CAS (9), JobScheduler reaper (7),
+  SleepWakeDetector cumulative (6) — all still green.
+- `tsc --noEmit` clean.
+- Side-effects review updated per-commit:
+  `upgrades/side-effects/unified-session-lifecycle-robustness.md`.

package/upgrades/side-effects/unified-session-lifecycle-robustness.md

@@ -239,3 +239,194 @@ no-silent-fallbacks ratchet doesn't count them: `ReapLog.read` (no log file ⇒
 empty list is correct, not degraded) and the §P5 transcript-tail read (an
 unreadable tail ⇒ no meaningful-advance signal this tick; treated as ambiguous,
 never as progress). Behavior unchanged.
+
+## Phase 2 — Commit #5: SessionWatchdog → ReapAuthority
+
+**Files:** `src/monitoring/SessionWatchdog.ts`,
+`tests/unit/session-lifecycle-phase-2-wiring.test.ts` (new).
+
+`handleEscalation` is now `async`; the final `EscalationLevel.KillSession` no
+longer calls a raw `tmux kill-session` — it resolves the instar session by
+`tmuxSession` and routes through
+`sessionManager.terminateSession(id, 'watchdog-stuck', { disposition: 'terminal', finalStatus: 'killed' })`.
+The authority's mandatory KEEP-guard + lease gate + protected-set check now
+apply: a session the guards would have kept survives a buggy watchdog. The raw
+`killTmuxSession` method is deleted; the LLM gate + stdin guard + signal
+escalations (CtrlC / SigTerm / SigKill) are unchanged.
+
+**Stand-down on KEEP (anti-thrash):** if the authority refuses the kill
+(`protected` / `not-lease-holder` / a KEEP-guard hold / `in-flight`), the
+watchdog logs the exact reason, records a `kept (<reason>)` intervention, and
+**clears escalationState**. It does not re-escalate against a guarded session
+every tick — the §P5 backstop owns operator-decision escalation for a
+persistently-stale session.
+
+**Tests:** existing SessionWatchdog tests (58) green; new wiring contract (3) green; typecheck clean.
+
+**Rollback:** revert this commit; the raw `killTmuxSession` is the only thing
+deleted and is recoverable from history.
+
+## Phase 2 — Commit #6: OrphanProcessReaper → exact-id + work-check + ReapAuthority
+
+**Files:** `src/monitoring/OrphanProcessReaper.ts`, `src/core/SessionManager.ts`,
+`tests/unit/session-lifecycle-phase-2-wiring.test.ts`.
+
+Three spec-faithful changes:
+1. **Exact-id classification.** The legacy `tmuxSession.startsWith(this.projectPrefix)`
+   substring match is replaced by EXACT membership in
+   `SessionManager.listKnownTmuxSessions()` — the new method returns every tmux
+   name instar has ever tracked (any status). A user-created tmux session that
+   happens to share the project prefix is now classified `external`, not
+   `instar-orphan`, so the reaper cannot false-reap a user pane.
+2. **60-min age = necessary, not sufficient.** Before any orphan kill the new
+   `processHasActiveChildren(pid)` helper (`pgrep -P`) is consulted; a positive
+   result vetoes the reap and surfaces a `Kept orphan PID … work check vetoed
+   reap` action. An uninspectable result returns `false` (allowed to proceed)
+   to preserve prior behavior — this gate is a soft veto layered on top of the
+   age gate, never an escalation.
+3. **Route through P0 when applicable.** When the orphan's tmuxSession matches a
+   CURRENTLY-tracked session (a scan/refresh race), the kill goes through
+   `terminateSession(id, 'orphan-reap', { disposition:'terminal', finalStatus:'killed' })`
+   so the authority's KEEP-guard + lease gate + reap-log entry + `sessionReaped`
+   emission apply. Otherwise the tracked record is already terminal and the raw
+   tmux-kill cleans up the stray pane.
+
+The server session remains excluded unconditionally.
+
+**Tests:** OrphanProcessReaper (9) + Phase-2 wiring (6) green; typecheck clean.
+
+**Rollback:** revert this commit. `listKnownTmuxSessions()` becomes unused but harmless.
+
+## Phase 2 — Commit #8: SessionRecovery → P1/P2 cross-check + recovery-bounce disposition
+
+**Files:** `src/monitoring/SessionRecovery.ts`, `src/core/SessionManager.ts`,
+`src/commands/server.ts`, `tests/unit/session-lifecycle-phase-2-wiring.test.ts`.
+
+Three spec-faithful changes:
+1. **P1/P2 cross-check** — a new shared `killForRecovery(name)` helper inside
+   `SessionRecovery` consults `deps.hasActiveProcesses` BEFORE any kill. When
+   the tmux pane has active child processes, the recovery DEFERS this attempt
+   and returns a structured `deferred-still-working` result with the correct
+   `failureType` (stall / context_exhaustion / crash / error_loop). All four
+   recovery paths route through this helper — `deps.killSession` is no longer
+   called directly from any recovery method.
+2. **`disposition:'recovery-bounce'`** — the dep's `killSession` is rewired in
+   server.ts to route through
+   `sessionManager.terminateSession(id, 'session-recovery', { disposition:
+   'recovery-bounce', finalStatus: 'killed', bypassRecoveryFlag: true })`. The
+   §P3 notifier is silent on recovery-bounce, so the user isn't told "shut
+   down" when the bounce immediately respawns; the reap-log still records it.
+3. **`bypassRecoveryFlag` (scoped)** — terminateSession gains an opt that
+   skips ONLY the `recovery-in-flight` KEEP-guard reason (not the whole guard).
+   Without it the recovery would refuse to kill its OWN in-flight session.
+   Other KEEP-guards (active subagent, recent-user-message, etc.) still apply
+   so a session mid-conversation is not killed-to-respawn under the cover of
+   "recovery."
+
+`SessionRecoveryDeps.killSession` is now `() => void | Promise<void>` so the
+implementation can await terminateSession.
+
+**Tests:** SessionRecovery (9) + terminate-CAS (9) + Phase-2 wiring (10) green; typecheck clean.
+
+**Rollback:** revert this commit. `bypassRecoveryFlag` becomes unused but harmless.
+
+## Phase 2 — Commit #9: wake-reaper → P1/P2 + cumulative sleep + ReapAuthority
+
+**Files:** `src/scheduler/JobScheduler.ts`, `src/core/SleepWakeDetector.ts`,
+`src/commands/server.ts`, `tests/unit/JobScheduler-reaper.test.ts`,
+`tests/unit/sleep-wake-cumulative.test.ts` (new),
+`tests/unit/session-lifecycle-phase-2-wiring.test.ts`.
+
+Three spec-faithful changes:
+1. **Cumulative sleep (SE-8).** `SleepWakeDetector.getCumulativeSleepMsBetween(startMs, endMs)`
+   sums the overlap of every recorded sleep window with the query range. The
+   wake-reaper now reads `cumulativeSleepProvider(runStartMs, now)` per run and
+   uses `effectiveElapsed = elapsedMs − cumulativeSleep` against its threshold —
+   a run that spanned multiple sleeps is no longer reaped early because the old
+   code credited only the single last `sleepDurationSeconds` event.
+2. **P1/P2 gate.** Before any kill, `sessionManager.hasActiveProcesses(sessionName)`
+   is consulted; on `true` the run is KEPT regardless of clock (spec: "a
+   progressing process is KEEP regardless of clock"). The deferred run is
+   counted as `skipped` and a structured log line names the reason.
+3. **Route through P0.** When a stuck-run session is currently tracked, the
+   kill goes through
+   `terminateSession(id, 'wake-reaper', { disposition:'terminal', finalStatus:'killed' })`
+   — the authority's protected-set + lease gate + reap-log + `sessionReaped`
+   emission apply. Untracked tmux panes fall back to the raw `killSession`.
+
+`reapStuckRuns` is now async; the timeout error message now names the effective-
+elapsed + cumulative-sleep subtraction instead of the single last sleep event.
+
+**Tests:** JobScheduler reaper (7, updated to async + new error contract) +
+SleepWakeDetector cumulative (6, new) + Phase-2 wiring (14) green; typecheck clean.
+
+**Rollback:** revert this commit. `getCumulativeSleepMsBetween` becomes unused
+but harmless.
+
+## Phase 3 — Commit #7: quota soft-check (bounded, force-kill via ReapAuthority)
+
+**Files:** `src/monitoring/SessionMigrator.ts`, `src/monitoring/QuotaManager.ts`,
+`tests/unit/session-lifecycle-phase-3-wiring.test.ts` (new).
+
+The quota migrator's force-kill path now goes through the single ReapAuthority,
+and grants a bounded extra-grace round to working sessions — without ever
+letting that grace push real usage to 100%/lockout.
+
+1. **Bounded soft-check (SE-9).** New `MigrationThresholds`:
+   `softCheckEnabled` (default true), `softCheckMaxUsagePercent` (default 95),
+   `softCheckExtraGraceMs` (default = `gracePeriodMs`). The kill loop computes
+   `softCheckActive = softEnabled && currentUsagePct ≤ softCeilingPct`. **Above**
+   the ceiling the soft check is **disabled** — quota's final authority cannot
+   be undermined when usage is already near 100%. When unknown,
+   `quotaUsagePercent` falls back to **100** (fail-closed posture: no grace
+   without proof we're below the ceiling).
+2. **One extra Ctrl+C grace round.** When the soft check is active AND
+   `isBuildOrAutonomousActive()` returns true, the session gets ONE more C-c +
+   `softCheckExtraGraceMs` wait before force-kill. The current implementation
+   uses a coarse signal — `state/build/build-state.json` fresh OR any
+   `autonomous/*.local.md` fresh under 30 min — which trades per-topic
+   precision for simplicity (the ceiling backstop bounds the worst case).
+3. **Route through ReapAuthority.** The force-kill goes through
+   `deps.terminateSession(id, 'quota-shed', { disposition: 'terminal',
+   finalStatus: 'killed' })` so the §P3 notifier surfaces "your session was
+   shut down — quota-shed" and the reap-log records it. Falls back to
+   `deps.killSession` only if `terminateSession` is unwired (older agents).
+4. **Tier-1 supervision seam.** A new `quota-force-kill-decision` event is
+   emitted with `{ tmuxSession, sessionId, jobSlug, currentUsagePct,
+   softCheckActive, workingSoftCheckFired }` so a future Haiku-wrapping
+   supervisor can validate the policy decision. The event is observability,
+   not a gate — the kill still happens.
+
+**Tests:** session-migrator existing (37) + Phase-3 wiring (6) green; typecheck clean.
+
+**Rollback:** revert this commit. The new thresholds default to safe values and
+the migrator dep stays optional, so older callers are unaffected.
+
+## Phase 3 — Commit (bonus): session label follows topic rename
+
+**Files:** `src/core/SessionManager.ts`, `src/messaging/TelegramAdapter.ts`,
+`src/commands/server.ts`, `tests/unit/session-rename-by-tmux.test.ts` (new),
+`tests/unit/session-lifecycle-phase-3-wiring.test.ts`.
+
+When the user renames a Telegram forum topic, the bound session's DISPLAY name
+follows the rename — but the operational identity (`tmuxSession` key + `id`
+UUID) stays intact, as the spec requires.
+
+1. **`SessionManager.renameSessionByTmux(tmuxSession, newName)`** — updates
+   `session.name` ONLY. NEVER touches `tmuxSession` (the tmux key + every
+   internal lookup) or `id` (state lookups). Idempotent; safe on unknown
+   tmuxSession; rejects empty / whitespace-only / non-string names.
+2. **`TelegramAdapter.setTopicRenamedHandler`** — wires a fire-and-forget
+   callback fired ONLY on a true rename (`forum_topic_edited` present AND the
+   name changed). Initial-capture and topic-creation cases do not fire.
+3. **server.ts wiring** — `setTopicRenamedHandler((topicId, newName) => {
+   sessionManager.renameSessionByTmux(telegram.getSessionForTopic(topicId), newName); })`.
+
+Because the renamed value is user-controlled, it flows through the same §P3
+sanitization (literal code spans) wherever it surfaces in user-facing notices.
+
+**Tests:** SessionManager rename (5) + Phase-3 wiring (9, including the bonus
+contracts) green; typecheck clean.
+
+**Rollback:** revert this commit; the handler stays optional, so older callers
+are unaffected.