instar 1.2.45 → 1.2.47

package/upgrades/1.2.46.md

@@ -0,0 +1,99 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fix, no new capability, no breaking change -->
+
+## What Changed
+
+**fix(framework): Telegram spawn path now honors the agent's configured framework (codex-cli agents stop spawning Claude sessions).**
+
+A follow-on to the framework-spawn-portability fix (v1.2.31). That fix
+made the fresh-spawn path (`spawnInteractiveSession`'s internal
+resolution) read the agent's resolved `config.sessions.framework`. But
+there are TWO paths that pick a framework, and the **Telegram message
+path** was missed.
+
+When a Telegram message arrives, `spawnSessionForTopic` resolves the
+framework via `resolveTopicFramework(topicId)`, which returns the
+module-level `_defaultFramework` for any topic without an explicit
+per-topic override (i.e. every fresh topic). `_defaultFramework` was
+initialized in `startServer` as:
+
+```ts
+const framework = frameworkFromEnv() ?? 'claude-code';
+```
+
+— sourced ONLY from the `INSTAR_FRAMEWORK` environment variable. The
+setup wizard sets `enabledFrameworks: ['codex-cli']` in config, NOT the
+env var, so for a codex-cli-only agent that didn't export
+`INSTAR_FRAMEWORK` (the common case), `frameworkFromEnv()` returned
+undefined and `_defaultFramework` fell back to `'claude-code'`. Worse,
+`spawnSessionForTopic` passes its resolved framework as the per-call
+`options.framework` to `spawnInteractiveSession` — and per-call wins
+over `config.framework`. So even though v1.2.31 correctly resolved
+`config.framework` to `codex-cli`, the Telegram path's wrong default
+overrode it and spawned a Claude session on every message.
+
+The fix: derive `_defaultFramework` from the agent's resolved runtime
+framework first, falling back to the env var only when that's unset:
+
+```ts
+const framework = config.sessions?.framework ?? frameworkFromEnv() ?? 'claude-code';
+```
+
+`config.sessions.framework` is the single resolved source
+(`resolveConfiguredFramework(sessions.framework, INSTAR_FRAMEWORK,
+enabledFrameworks)` from `Config.load`), so both the fresh-spawn path
+and the Telegram path now agree. A codex-cli-only agent spawns Codex
+sessions whether the session is created directly via the API or
+triggered by a Telegram message.
+
+No migration needed — the fix is a server-startup derivation. Deployed
+codex-cli agents get the correct behavior the moment they update and
+restart cleanly. (Note: a clean restart IS required — an agent running
+an older server process keeps the old `_defaultFramework` in memory
+until restarted, even after its files update.)
+
+## Evidence
+
+The original failure: a codex-cli-only agent ("codey") with
+`enabledFrameworks: ['codex-cli']` and no `INSTAR_FRAMEWORK` env spawned
+a Claude Code (Opus 4.7) session every time it answered a Telegram
+message — including in brand-new topics. A direct `/sessions/create`
+API spawn correctly produced Codex, which masked the bug (the API path
+doesn't pass the Telegram default).
+
+Regression coverage in `tests/unit/framework-spawn-portability.test.ts`
+(2 new assertions):
+
+1. `server.ts` derives `_defaultFramework` from `config.sessions?.framework`
+   ahead of the `frameworkFromEnv()` fallback.
+2. The pre-fix env-only derivation (`const framework = frameworkFromEnv()
+   ?? 'claude-code';`) no longer appears in `server.ts`.
+
+These join the existing 10 framework-spawn-portability tests (precedence
+of `resolveConfiguredFramework`, the spawn-path source assertions, and
+the `Config.load` wiring) — 12 tests total, all passing. `tsc --noEmit`
+clean, lint clean.
+
+Empirical confirmation against a live codex-cli agent (message it, watch
+the spawned session run `codex --model gpt-5.3-codex` instead of
+`claude`) is performed as part of the rollout, per the bug-fix evidence
+bar — no "fixed" claim without reproducing the corrected behavior.
+
+## What to Tell Your User
+
+If you set up an agent to run on Codex, it will now correctly run on
+Codex when it answers your messages — not just when a session is
+created some other way. Before this fix, a Codex-only agent could still
+quietly start up on Claude whenever you messaged it, because the
+message-handling path was reading the wrong setting. You don't need to
+do anything beyond letting your agent update and restart; the Codex
+choice you made at setup is now respected on every path.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Telegram message path honors configured framework | Automatic — codex-cli agents spawn Codex on incoming messages |
+| Single framework source of truth across both spawn paths | Automatic — derived from your install-time framework choice |

package/upgrades/1.2.47.md

@@ -0,0 +1,36 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+PR 7 of the tunnel-failure-resilience chain. This is the security cleanup that makes the backup-tunnel feature safe to use: whenever a backup relay episode ends, the agent now rotates your dashboard PIN and access token.
+
+**Why it matters.** While a backup relay is active, your dashboard traffic — including the PIN and any private view links — briefly passes through a third-party operator's machines. PIN rotation alone is not enough: the private view links are signed with your access token, so a copied link would keep working forever unless the token itself changes. This release rotates both. The moment the backup ends, the old PIN stops working and every previously-shared private view link becomes invalid.
+
+**Where it triggers.** Every terminal exit from a backup relay episode rotates: an operator stop/shutdown while the relay was up, and — most importantly — boot-recovery. If the agent died mid-relay-episode, a flag persisted to disk causes rotation to run on the next boot **before the server accepts any API traffic**, so a relay operator who saw the old credentials can't use them against the freshly-started server.
+
+**How it takes effect immediately.** The auth layer now reads the token live on every request instead of capturing it once at startup. So rotation invalidates the old token and old signed URLs instantly, with no restart. Existing behavior is unchanged when no rotation happens.
+
+## What to Tell Your User
+
+- If a backup tunnel was ever used, you'll get a private message with a fresh dashboard PIN once it's no longer needed. Any open dashboard tab will ask you to sign in again with the new PIN.
+- Any private view link you shared while the backup was active will stop working — that's deliberate, so the backup operator can't reuse it.
+- If nothing ever falls back to a backup, you'll never see any of this; normal operation is unchanged.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Credential rotation on relay-episode end | Automatic — fires on stop/shutdown and boot-recovery whenever a backup relay was in use; new PIN arrives in the owner DM |
+| Live auth-token resolution | Automatic — the server now honors a rotated token immediately, no restart |
+
+## Evidence
+
+- Spec: `specs/dev-infrastructure/tunnel-failure-resilience.md` Part 6. Side-effects: `upgrades/side-effects/tunnel-credential-rotation.md`.
+- Tests: `tests/unit/auth-middleware-live-token.test.ts` (5) asserts both sides of the rotation boundary — the old bearer token AND an old HMAC-signed view URL are rejected the instant the live token changes, and a URL signed with the new token works. `tests/unit/tunnel-credential-rotation.test.ts` (6) asserts the lifecycle: relay-active→idle rotates, a non-relay stop does not, a thrown rotator leaves the pending flag set for retry, and a fresh manager restores the flag and rotates on boot-recovery.
+- No regression: 75 auth + tunnel tests pass, including the existing string-form auth-middleware suites (the refactor is backward compatible).
+
+## Rollback
+
+The middleware change is backward compatible (it still accepts a plain string). Revert = restore the string argument at the AgentServer auth callsite, drop the manager rotation methods and the `stop()` trigger, and remove the server.ts rotator closure + boot-recovery call. No config schema or persistent-state migration — a rotated PIN/token is just a new value.

package/upgrades/side-effects/codex-telegram-default-framework.md

@@ -0,0 +1,106 @@
+# Side-effects review — Telegram default-framework fix (codex agents)
+
+**Scope**: Follow-on to framework-spawn-portability (v1.2.31). The
+original fix corrected the fresh-spawn path
+(`spawnInteractiveSession`'s internal framework resolution) but missed
+the Telegram message path (`spawnSessionForTopic` →
+`resolveTopicFramework` → `_defaultFramework`). `_defaultFramework` was
+sourced from `frameworkFromEnv()` only, so a codex-cli-only agent
+without the `INSTAR_FRAMEWORK` env var defaulted to claude-code and
+spawned Claude on every Telegram message — and because the Telegram
+path passes its framework as the per-call `options.framework`
+(highest precedence), it overrode the correct `config.framework`.
+Governed by the existing converged + approved spec
+`specs/dev-infrastructure/framework-spawn-portability.md`.
+
+**Files touched**:
+- `src/commands/server.ts` — one line in `startServer`:
+  `const framework = frameworkFromEnv() ?? 'claude-code';`
+  →
+  `const framework = config.sessions?.framework ?? frameworkFromEnv() ?? 'claude-code';`
+  plus an explanatory comment. `config.sessions.framework` is the
+  resolved runtime framework (`resolveConfiguredFramework` output from
+  `Config.load`, line 635), so the Telegram default now matches the
+  fresh-spawn path.
+- `tests/unit/framework-spawn-portability.test.ts` — 2 new source-grep
+  assertions (derivation reads `config.sessions?.framework`; the
+  env-only derivation is gone).
+
+**Under-block**: None. The change makes a previously-ignored config
+field authoritative for the Telegram default. There is no path where a
+framework that *should* spawn is now suppressed: per-topic overrides
+(`_topicFrameworksStore` / `_topicFrameworks`) still win over the
+default (they're checked first in `resolveTopicFramework`), and the
+`INSTAR_FRAMEWORK` env still applies as a fallback when
+`config.sessions.framework` is somehow unset.
+
+**Over-block**: None. A claude-code agent (config.sessions.framework =
+'claude-code') still resolves to claude-code. A codex-cli agent now
+correctly resolves to codex-cli instead of silently falling back to
+claude-code. The only behavior change is the bug being fixed.
+
+**Level-of-abstraction fit**: The Telegram default now reads the same
+single resolved value (`config.sessions.framework`) that the
+SessionManager's internal resolution reads. One source of truth, both
+spawn paths. `resolveTopicFramework`'s precedence (per-topic store >
+per-topic config map > default) is unchanged — only the *default's*
+source is corrected.
+
+**Signal vs authority**: Compliant. `config.sessions.framework`,
+`INSTAR_FRAMEWORK`, and per-topic overrides are all SIGNALS;
+`resolveConfiguredFramework` (in Config.load) is the single AUTHORITY
+that resolves the agent-level framework, and `resolveTopicFramework`
+layers per-topic overrides on top. No new authority introduced.
+
+**Interactions**:
+- `resolveTopicFramework` callers (the Telegram spawn path) now get the
+  correct default. The per-topic `/route` override path is unaffected
+  (it sets `_topicFrameworksStore`, checked before the default).
+- `spawnSessionForTopic` passes `framework` as `options.framework` to
+  `spawnInteractiveSession`. With the fix, that value is now correct
+  for codex-cli agents, so the per-call override and the internal
+  `config.framework` resolution agree (no conflict).
+- `resolvedFramework` (used a few lines later to pick the
+  IntelligenceProvider for relationships/shared intelligence) now also
+  reflects the configured framework — correct: a codex-cli agent's
+  shared intelligence provider should match its framework.
+
+**External surfaces**: None. No new API endpoint, no new config field
+(the `INSTAR_FRAMEWORK` env and `enabledFrameworks` config already
+existed), no CLI change.
+
+**Migration parity**: No agent-installed file change. The fix is a
+server-startup derivation; deployed codex-cli agents get correct
+behavior on their next update + clean restart. IMPORTANT operational
+note (documented in NEXT.md): an agent running an older server process
+keeps the stale `_defaultFramework` in memory until restarted, even
+after its files update. This is the version-skew pattern — "updated"
+≠ "running the update". The codey incident that surfaced this bug was
+partly this: the fix-bearing files were present but a long-running
+process still served the old default.
+
+**Rollback cost**: Trivial. Revert one line in server.ts + the 2 test
+assertions.
+
+**Tests**:
+- 12/12 `framework-spawn-portability.test.ts` (10 existing + 2 new).
+- `tsc --noEmit` clean. `npm run lint` clean.
+- Empirical end-to-end confirmation (live codex-cli agent spawns
+  `codex --model gpt-5.3-codex` on a Telegram message, not `claude`)
+  is performed during rollout per the bug-fix evidence bar.
+
+**Decision-point inventory**:
+1. Derive `_defaultFramework` from `config.sessions.framework` (vs.
+   adding yet another env read or a new config field) — reuses the
+   single resolved value the rest of the system already trusts. No new
+   knob.
+2. Keep `frameworkFromEnv()` + `'claude-code'` as fallbacks (vs.
+   removing them) — defense-in-depth: if `config.sessions.framework`
+   is ever unset (older Config.load, or a hand-edited config), the env
+   var and historical default still apply. The fix only re-orders
+   precedence to put the resolved config value first.
+3. Regression test via source-grep (vs. spinning up a full server) —
+   `_defaultFramework` is module-private state set inside the large
+   `startServer`; a source-grep assertion that the derivation reads
+   `config.sessions?.framework` is the proportionate guard, matching
+   the existing framework-spawn-portability spawn-path assertions.

package/upgrades/side-effects/tunnel-credential-rotation.md

@@ -0,0 +1,88 @@
+# Side-effects review — credential rotation (PR 7 of tunnel-failure-resilience chain)
+
+**Scope (PR 7 of the chain):** Make `authToken` + `dashboardPin`
+rotation real on every terminal exit from `relay-active`, plus
+boot-recovery. The `rotationPending` flag (set on relay-active entry in
+PR 5, persisted to `tunnel.json`) is now consumed: rotating the
+authToken invalidates every previously-signed view URL and the dashboard
+session — the documented UX cost of having briefly routed private
+traffic through a third-party relay. Spec Part 6.
+
+**Files touched:**
+- `src/server/middleware.ts` — `authMiddleware` accepts `string | (() =>
+  string | undefined)` and resolves the token **per request**, so a
+  runtime rotation takes effect immediately (no restart). Backward
+  compatible: the string form is byte-identical to before.
+- `src/server/AgentServer.ts` — wires the live getter
+  `authMiddleware(() => this.config.authToken, …)`. `this.config` is set
+  in the constructor and never reassigned, so the getter always reads the
+  shared, mutable config object.
+- `src/tunnel/TunnelManager.ts` — `setCredentialRotator(fn)`,
+  `runCredentialRotation(reason)` (gated on `rotationPending`,
+  clears-only-after-success), `recoverPendingRotation()` (boot path), and
+  a rotation trigger at the end of `stop()`.
+- `src/commands/server.ts` — the rotator closure (regen PIN + authToken →
+  `liveConfig.set` + mutate the in-memory `config` → owner DM with the new
+  PIN), wired right after tunnel construction; boot-recovery awaited
+  **before** `server.start()`.
+- Tests: `tests/unit/tunnel-credential-rotation.test.ts` (6),
+  `tests/unit/auth-middleware-live-token.test.ts` (5).
+
+**Over-block:** None. The middleware resolves `string → itself`, so all
+existing string callers and the 75 auth/tunnel tests are unchanged.
+
+**Under-block:** The getter returning `undefined` means "open" (the
+documented test/dev passthrough), same as the old `authToken === undefined`
+behavior. In production `authToken` is always set (init generates it;
+rotation always assigns a fresh non-empty UUID). The rotator does
+`config.authToken = newToken` as a single synchronous assignment after
+the `liveConfig.set` calls — there is no window where the live token is
+`undefined`; a concurrent in-flight request reads either the old or the
+new token, never empty. The instant the assignment lands, the old bearer
+token and old signed URLs are rejected (asserted by the rotation tests).
+
+**Level-of-abstraction fit:** The manager owns the WHEN (lifecycle
+triggers + the `rotationPending` invariant); the injected closure owns
+the WHAT (regenerate/persist/notify). The manager never imports config or
+messaging. Mirrors the PR 6 `attachTelegram` seam.
+
+**Signal vs authority:** `rotationPending` is the single-writer
+authoritative marker owned by `TunnelLifecycle`. `runCredentialRotation`
+clears it **only after** the rotator resolves; a thrown rotator leaves it
+set so the next `stop()` or next boot retries (tested). No abstraction
+treats a low-context signal as authority.
+
+**Interactions:**
+- Boot-recovery runs before `server.start()` (verified ordering:
+  rotator wired at tunnel-construction ~L4846 → boot-recovery at L7305 →
+  listen inside `server.start()`). The owner DM uses `sendToOwnerDM`
+  (private chat), so it does not depend on the Dashboard topic being
+  ensured yet.
+- The startup `dashboardPin` auto-gen (`if (!config.dashboardPin)`) runs
+  after boot-recovery, so a boot-recovery rotation is not clobbered.
+- `signViewPath` (routes.ts) and `verifyViewSignature` (middleware) both
+  read the live token, so post-rotation: new view URLs are signed with
+  the new token and old shared URLs fail verification — the intended
+  invalidation (tested).
+- The 6-digit PIN keeps the existing `Math.random` generator (a
+  convenience factor, not the primary secret); `authToken` is
+  `randomUUID()` and is the HMAC key. No change to the secret model.
+
+**Migration parity:** No agent-installed files change. The rotation is
+runtime behavior in `server.ts` (every agent runs the new server after
+update) and an internal middleware refactor; no new config field, no
+CLAUDE.md/hook change (those land in PR 9). `rotationPending` already
+existed in the persisted schema since PR 5.
+
+**Tier-2/Tier-3 note:** PR 7 adds no HTTP route — per spec Part 8 the
+HTTP-assertable "feature is alive" surface is the `/tunnel` route in
+PR 9. PR 7's security guarantee is covered by the live-token middleware
+unit tests (both sides of the boundary + view-URL invalidation) and the
+manager rotation-lifecycle tests; the boot-recovery wiring is verified at
+the `server.ts` call site.
+
+**Rollback cost:** Low. The middleware change is backward compatible;
+revert = restore the string arg at the AgentServer callsite, drop the
+manager rotation methods + `stop()` trigger, and remove the server.ts
+rotator closure + boot-recovery call. No schema or persistent-state
+migration (rotated PIN/token are just new values).