instar 1.2.29 → 1.2.31

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-22T17:48:59.540Z",
-  "instarVersion": "1.2.29",
+  "generatedAt": "2026-05-22T18:31:32.419Z",
+  "instarVersion": "1.2.31",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -1448,7 +1448,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "b6817bdf6872a71f351ff61e60d95143c553198d05d8f75b3aa9545f5b9dac44",
+      "contentHash": "c8a43e38d2707bf0f1e7f3bfc958b5f6f885a4cfc383cb99135100caad6fc901",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {

package/upgrades/1.2.30.md

@@ -0,0 +1,60 @@
+# Upgrade Guide — v1.2.30 (Codex creates only Lifeline topic)
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**Fix: duplicate Dashboard topic in the Codex Telegram setup.**
+
+Real-user retest showed two "Dashboard" topics in the Telegram
+group — one created by the Codex agentic flow (📊), one by the
+instar server on boot (📢). The Codex flow was creating all four
+system topics (Lifeline, Updates, Dashboard, Attention), but the
+server ALSO creates Dashboard / Updates / Attention on its first
+boot. They didn't coordinate, so Dashboard got made twice.
+
+Lifeline never duplicated because the Codex flow persists its ID
+and the server reuses it. The fix extends that pattern: the Codex
+flow now creates ONLY Lifeline. The server creates Dashboard,
+Updates, and Attention like it always has — with its own
+canonical intros, emojis, colors, and the dashboard-link wiring.
+
+The Lifeline orientation message now tells the user that "a few
+more topics will appear automatically once my server starts," so
+the brief single-topic state between Codex-done and server-boot
+doesn't look incomplete.
+
+Spec: `specs/dev-infrastructure/codex-only-lifeline-topic.md`.
+ELI16: `specs/dev-infrastructure/codex-only-lifeline-topic.eli16.md`.
+Side-effects: `upgrades/side-effects/fix-codex-only-lifeline-topic.md`.
+
+## What to Tell Your User
+
+The setup no longer creates a duplicate Dashboard topic. You'll
+get one of each system topic, created by the part of instar that
+owns it. The Lifeline topic now mentions that the other topics
+appear automatically once your agent's server starts.
+
+(Separately: if your dashboard link is missing, it's usually
+because the Cloudflare tunnel can't connect — often a temporary
+rate limit. Two follow-up improvements are planned: a clear
+"tunnel couldn't connect" message in the Dashboard topic, and a
+pool of backup tunnel providers.)
+
+## Summary of New Capabilities
+
+No new capabilities. Duplicate-topic bug fix.
+
+## Evidence
+
+Reproduction prior: live instar-codey config showed
+`config.dashboardTopicId = 14` (server's "📢 Dashboard") plus a
+separate Codex-created "📊 Dashboard" with no config reference.
+The user's screenshot showed both in the chat list.
+
+After fix: 81 wizard tests pass; the topic-creation canary now
+asserts the prompt creates ONLY Lifeline and explicitly forbids
+creating the other three. The retired Attention/Updates/Dashboard
+color codes are no longer hard-coded in the prompt (only
+Lifeline's remains).

package/upgrades/1.2.31.md

@@ -0,0 +1,90 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fix, no new capability, no breaking change -->
+
+## What Changed
+
+**fix(framework): Codex-only agents now spawn Codex sessions on every path.**
+
+A Codex-only agent ("codey") spawned a Claude Code session when messaged on
+Telegram — even though the install was Codex-only. The whole point of a
+codex-cli install is that the agent runs on Codex, so this was a direct
+framework-portability violation.
+
+Two compounding bugs caused it:
+
+1. **`spawnInteractiveSession` hardcoded the framework default.** The
+   interactive-session path — the one that handles incoming Telegram/Slack
+   messages — resolved its framework as `options?.framework ?? 'claude-code'`.
+   It never read the agent's config or the `INSTAR_FRAMEWORK` env. The
+   messaging callsites never pass `options.framework`, so this path ALWAYS
+   defaulted to claude-code.
+
+2. **The runtime read a different config field than the wizard wrote.** The
+   setup wizard persists the framework choice as top-level
+   `config.enabledFrameworks` (e.g. `['codex-cli']`). But the runtime's
+   `resolveConfiguredFramework` only consulted `sessions.framework` and
+   `INSTAR_FRAMEWORK` — neither of which the wizard sets. So a codex-cli agent
+   had `enabledFrameworks: ['codex-cli']` set, both other fields empty, and the
+   runtime resolved claude-code.
+
+The fix makes `enabledFrameworks` the authority that flows into the runtime.
+`resolveConfiguredFramework` now takes `enabledFrameworks` as a third input
+with precedence `sessions.framework` → `INSTAR_FRAMEWORK` env →
+`enabledFrameworks[0]` → `'claude-code'`. `Config.load` stores the resolved
+value as a new `config.framework` field, and BOTH spawn paths
+(`spawnSession` for jobs, `spawnInteractiveSession` for messages) now read it.
+A per-call `options.framework` override still wins, so a caller can force a
+specific framework for one session.
+
+Because the fix derives the framework at config-load time from a field existing
+agents already have on disk, deployed Codex agents are fixed the moment they
+update and reload — no reinstall, no migration.
+
+## Evidence
+
+The original failure: messaging codey (an agent installed with
+`enabledFrameworks: ['codex-cli']`, no `sessions.framework`, no
+`INSTAR_FRAMEWORK` env) in its Lifeline topic spawned a Claude Code session.
+
+10 new unit tests in `tests/unit/framework-spawn-portability.test.ts`
+reproduce and lock the fix:
+
+1. `resolveConfiguredFramework` returns codex-cli when only
+   `enabledFrameworks: ['codex-cli']` is set (the codey configuration) — was
+   claude-code before the fix.
+2. Explicit `sessions.framework` still wins over enabledFrameworks.
+3. `INSTAR_FRAMEWORK=codex` env wins over an enabledFrameworks of claude-code.
+4. `INSTAR_FRAMEWORK=claude` env wins over an enabledFrameworks of codex-cli
+   (the new explicit-claude env branch).
+5. Empty/absent inputs still resolve to the claude-code historical default.
+6. Per-call `options.framework` is highest precedence.
+7–8. Source-grep assertions that both `spawnSession` and
+   `spawnInteractiveSession` resolve via `this.config.framework` (catches a
+   regression that re-hardcodes the default).
+9–10. `Config.load` wiring — `enabledFrameworks` flows into
+   `config.framework`.
+
+All 11 existing `frameworkPrerequisite.test.ts` tests still pass — the shared
+resolver behaves identically for every previously-covered case. `tsc --noEmit`
+clean, lint clean.
+
+## What to Tell Your User
+
+If you set up an agent to run on Codex, it will now correctly run on Codex
+every time — including when you message it. Before this fix, a Codex-only agent
+could quietly start up on Claude instead when you sent it a message, which was
+the wrong engine entirely.
+
+You do not need to do anything. There is no reinstall and no setup to redo. The
+next time your agent updates and restarts, it reads the framework choice already
+saved from when you set it up, and uses it for every session from then on.
+Agents set up on Claude, or set up to use both, keep working exactly as before.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Codex-only agents spawn Codex on all paths (jobs + messages) | Automatic — derived from your install-time framework choice |
+| Existing Codex agents fixed on update | Automatic — no reinstall or migration; the choice is read from disk at startup |

package/upgrades/side-effects/fix-codex-only-lifeline-topic.md

@@ -0,0 +1,83 @@
+# Side-effects review — Codex creates only Lifeline
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: OVER-creation. The Codex flow created all 4 system topics
+AND the server created 3 of them on boot, yielding duplicate
+Dashboard (and latent duplicate risk for Updates/Attention).
+
+After: precisely scoped. Codex creates only Lifeline (which the
+server reuses by persisted ID). Server creates the other 3.
+Single creator per topic. No duplicates.
+
+## 2. Level-of-abstraction fit
+
+Prompt-content change only — steps 13 + 14 of
+`buildTelegramAgenticPrompt`. No new functions, no signature
+change, no server-side change. Follows the existing ownership
+boundary (server owns Dashboard/Updates/Attention; Lifeline is
+shared via `config.lifelineTopicId`).
+
+## 3. Signal vs Authority compliance
+
+- The server's `ensureDashboardTopic` / `ensureAgentUpdatesTopic`
+  / `ensureAgentAttentionTopic` remain the single AUTHORITY for
+  those three topics.
+- `config.lifelineTopicId` remains the coordination AUTHORITY
+  between the Codex flow and the server's `ensureLifelineTopic`.
+- The Codex flow no longer emits create-SIGNALS for the three
+  server-owned topics.
+
+## 4. Interactions with adjacent systems
+
+- **Server `ensureDashboardTopic` / `ensureAgentUpdatesTopic` /
+  `ensureAgentAttentionTopic`**: unchanged. They now run without
+  a Codex-created duplicate to collide with.
+- **Server `ensureLifelineTopic`**: unchanged. Still reuses
+  `config.lifelineTopicId` written by the Codex flow.
+- **`runSendLifelineGreeting`** (post-server greeting): unchanged.
+  Still reads `lifelineTopicId` from config and posts the
+  agent's first hello.
+- **`broadcastDashboardUrl`**: unchanged. Posts the dashboard
+  link to `config.dashboardTopicId` (set by the server's
+  `ensureDashboardTopic`) once a tunnel is up.
+- **Tests**: one test rewritten (was "creates the 4 canonical
+  system topics" → now "creates ONLY the Lifeline topic"); the
+  other 80 wizard tests unchanged.
+
+## 5. Rollback cost
+
+Trivial. Prompt-content change in two steps. `git revert`
+restores the 4-topic creation (and the duplicate).
+
+## 6. Backwards compatibility / drift surface
+
+Fully backwards-compatible.
+
+- Existing agents already set up: unaffected — their topics
+  already exist; the server's ensure functions are idempotent on
+  their stored IDs.
+- New Codex installs: get exactly 4 topics, one creator each, no
+  duplicates.
+- Claude wizard path: untouched.
+- No config schema change. No agent-installed-files change.
+
+Drift surface reduced: the Codex prompt no longer hard-codes the
+Dashboard/Updates/Attention names + colors, so it can't drift
+from the server's TOPIC_STYLE constants. Only Lifeline's color
+(9367192) remains in the prompt, matching SYSTEM.
+
+## 7. Authorization / Trust posture
+
+No change. Same Codex spawn flags, same Bot API access.
+
+## Outcome
+
+Ship. Closes the duplicate-Dashboard bug by restoring the natural
+ownership boundary: server owns its three system topics; Codex
+owns only Lifeline (the shared coordination point). The
+no-dashboard-link issue is separate (Cloudflare rate-limit) and
+addressed by two tracked follow-ups (tunnel-failure user
+notification + backup tunnel pool).

package/upgrades/side-effects/framework-spawn-portability.md

@@ -0,0 +1,92 @@
+# Side-effects review — framework-spawn portability (codex agents spawn Codex)
+
+**Scope**: A Codex-only agent ("codey") spawned a Claude Code session when
+messaged on Telegram. Two compounding bugs: (1) `spawnInteractiveSession`
+hardcoded `'claude-code'` and never read config/env; (2) the runtime's
+`resolveConfiguredFramework` read `sessions.framework` + `INSTAR_FRAMEWORK`,
+neither of which the wizard sets — the wizard persists `enabledFrameworks`.
+So the runtime always resolved claude-code for wizard-installed Codex agents.
+
+**Files touched**:
+- `src/core/types.ts` — add optional `framework?: 'claude-code' | 'codex-cli'`
+  to `SessionManagerConfig` (the resolved runtime framework).
+- `src/core/Config.ts` — `resolveConfiguredFramework` takes a third arg
+  `enabledFrameworks`; new precedence configValue → env → enabledFrameworks[0]
+  → 'claude-code'; explicit `claude`/`claude-code` env branch added; `loadConfig`
+  passes `fileConfig.enabledFrameworks` and stores the result on
+  `sessions.framework` (the SessionManagerConfig field).
+- `src/core/SessionManager.ts` — `spawnInteractiveSession` replaces the
+  hardcoded default with `resolveInteractiveFramework({ perCall, configFramework:
+  this.config.framework, envFramework })`; `spawnSession` changes
+  `configFramework: undefined` → `this.config.framework`.
+- `tests/unit/framework-spawn-portability.test.ts` — 10 tests: precedence of
+  resolveConfiguredFramework (incl. enabledFrameworks fallback + explicit-claude
+  env), source-grep that both spawn paths read config.framework, and Config.load
+  wiring (enabledFrameworks → config.framework).
+
+**Under-block**: None. The fix makes a previously-ignored config field
+authoritative. There is no path where a framework that *should* spawn is now
+suppressed — per-call override and explicit config/env all still win.
+
+**Over-block**: None. A codex-cli agent will now correctly REFUSE to silently
+fall back to Claude. If a caller genuinely wants a one-off Claude session on a
+Codex agent, the per-call `options.framework` override still does that — it sits
+at the top of the precedence chain. So the "block" here is exactly the intended
+behavior (honor the install choice), with a documented escape hatch.
+
+**Level-of-abstraction fit**: Framework resolution stays in one place
+(`resolveConfiguredFramework` / `resolveInteractiveFramework`). The spawn paths
+do not re-implement precedence; they pass their three inputs and take the
+answer. `enabledFrameworks` (install choice) is reduced to a single resolved
+`config.framework` at load time, so SessionManager never has to know about the
+array shape. Correct layering: array-of-enabled is an install concept; the
+runtime sees one resolved framework.
+
+**Signal vs authority**: Compliant. `enabledFrameworks`, env, and per-call
+options are all SIGNALS fed into the resolver. The resolver
+(`resolveConfiguredFramework`) is the single AUTHORITY that picks one framework.
+No spawn-path makes its own framework decision anymore — both defer to the
+resolved value.
+
+**Interactions**:
+- `spawnSession` (scheduled jobs) and `spawnInteractiveSession` (messages) now
+  resolve identically. Before, only spawnSession read env; the interactive path
+  was the one that hit the bug. They are now symmetric.
+- `frameworkBinaryPaths[framework] ?? claudePath` fallback is unchanged — if a
+  codex-cli framework has no binary path mapped, it still falls back to
+  claudePath. That fallback is a *binary-path* concern, separate from framework
+  *selection*; out of scope here. For correctly-installed Codex agents the codex
+  binary path is populated by `detectCodexPath()` in loadConfig.
+- No change to `checkFrameworkPrerequisite` or the parity sentinel — they read
+  `enabledFrameworks` directly and are unaffected by the new derived field.
+
+**External surfaces**: None. No new API endpoint, no new config field the user
+writes (the new `framework` is derived, not user-authored), no CLI change. The
+`enabledFrameworks` field already existed and was already written by the wizard.
+
+**Migration / existing agents**: No migration needed. The fix is a config-LOAD
+derivation. Deployed Codex agents already have `enabledFrameworks: ['codex-cli']`
+on disk (their install wrote it). The moment they update and the server reloads
+config, `config.framework` resolves to codex-cli and both spawn paths honor it.
+Verified by the Config.load wiring test.
+
+**Rollback cost**: Trivial. Revert three source files + the test. The derived
+field is optional; nothing persists it to disk, so a revert leaves no orphaned
+state.
+
+**Tests**: 10/10 new tests pass; 11/11 existing `frameworkPrerequisite.test.ts`
+pass (no regression in the shared resolver). `npx tsc --noEmit` clean.
+`npm run lint` clean.
+
+**Decision-point inventory**:
+1. Derive `config.framework` at load (vs. teach every spawn path to read
+   `enabledFrameworks` itself) — single resolution point, single authority,
+   keeps SessionManager ignorant of the array shape. Chosen.
+2. `enabledFrameworks[0]` slots BELOW env (vs. above) — an explicit
+   `INSTAR_FRAMEWORK` env at boot is a deliberate per-boot override and should
+   beat the persisted install default. Matches the existing env-over-default
+   intent.
+3. No init-time write of `sessions.framework` (vs. backfilling it) — the
+   load-time derivation already fixes existing agents with zero migration; a
+   redundant on-disk write is deferred as unnecessary (noted out-of-scope in the
+   spec).