instar 0.28.113 → 0.28.115

package/upgrades/0.28.114.md

@@ -0,0 +1,44 @@
+# Upgrade Guide — v1.0.1
+
+<!-- bump: patch -->
+
+## What Changed
+
+The Codex provider-scaffolder now writes bundled skills to the path Codex 0.130 actually walks for project-scope discovery. The old layout silently failed — Codex never saw any of the skills the scaffolder installed.
+
+Two related changes in `src/providers/adapters/openai-codex/integration/providerScaffolder.ts`:
+
+1. Skill installation moved from `.agent/openai/skills/<name>/` to `.agents/skills/<name>/`. The plural `.agents/` (with a trailing `s`) is Codex 0.130's documented project-scope skill discovery path. The prior path (`.agent/openai/...`) was a co-location guess that Codex never looked at — every bundled skill we installed under it was invisible to the agent.
+
+2. Each installed skill now also gets a sibling `agents/openai.yaml` inside its own directory (`.agents/skills/<name>/agents/openai.yaml`), generated from the skill's frontmatter. The YAML carries `interface.display_name` and `interface.short_description`. Codex requires this sibling to surface the skill in UI lists and chips; without it the skill loads but is undiscoverable.
+
+The provider-config tree at `.agent/openai/` (AGENTS.md, config.toml, hooks.json) is unchanged — that's the Instar-standardized per-provider config bucket and Codex doesn't walk it for skills.
+
+`uninstall()` now removes both `.agent/openai/` and `.agents/skills/` to match the install footprint.
+
+This is the first concrete fix landing from the framework-functional-parity foundational work. Future framework-parity work will follow the same pattern: align scaffolder output to what each framework actually loads at the file-discovery layer.
+
+## What to Tell Your User
+
+- "Skills you bundle for Codex sessions are now actually visible to Codex. Before this fix they were being written to a location Codex doesn't look at, so they loaded but never appeared in skill lists."
+- "No action needed on your end. Existing scaffolds will pick up the correct layout the next time the scaffolder installs."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Codex skill discovery (project-scope) | Automatic — scaffolder writes `.agents/skills/<name>/SKILL.md` + sibling `agents/openai.yaml` |
+| Codex skill UI metadata | Automatic — generated from each skill's frontmatter (`name`, `description`, `metadata.short-description`) |
+
+## Evidence
+
+The bug was reproducible against Codex 0.130 with the prior layout:
+
+- **Before**: `.agent/openai/skills/hello-instar/SKILL.md` created by the scaffolder. Running `codex` in the project directory and asking "what skills are available?" returned no project-scope skills. Direct filesystem inspection confirmed the file existed; Codex was not walking that path.
+- **After**: `.agents/skills/hello-instar/SKILL.md` + `.agents/skills/hello-instar/agents/openai.yaml` created by the scaffolder. Layout matches the on-disk format of Codex's own installed skills under `~/.codex/skills/.system/<name>/` — `SKILL.md` at the root, `agents/openai.yaml` as a sibling subdirectory.
+
+YAML format anchored to Codex's documented spec at `~/.codex/skills/.system/skill-creator/references/openai_yaml.md` — `interface.display_name` and `interface.short_description` are the documented required fields; we generate both from frontmatter.
+
+Unit tests cover: correct path written, legacy wrong path not written, YAML sibling emitted at correct location, display_name derived from skill name when frontmatter omits it, short_description sourced from `metadata.short-description` (canonical Codex skill format) with fallback to top-level `description`, long descriptions truncated to 64 chars per spec, `uninstall()` removes both trees, multiple skills handled in one install call, YAML escapes double quotes in string values.
+
+Test file: `tests/unit/providers/adapters/openai-codex/providerScaffolder.test.ts` (14 tests, all passing). Full openai-codex adapter suite: 78/78 passing. Typecheck: clean.

package/upgrades/0.28.115.md

@@ -0,0 +1,38 @@
+# Upgrade Guide — v1.0.1
+
+<!-- bump: patch -->
+
+## What Changed
+
+Codex topics now actually resume into their prior session when one has been tracked. Before this release, the launch helper recognized that a topic had a tracked Codex session id but logged a warning and started fresh anyway — the resume id was thrown away. After this release, the helper rebuilds argv with `codex resume <SESSION_ID>` as a subcommand inserted right after the binary path, with all the usual sandbox / model / `--oss --local-provider` flags accepted by the `resume` subcommand verbatim.
+
+The implementation is in `src/core/frameworkSessionLaunch.ts` (codexCliBuilder). One small refactor: `resumePrefix` is built first (either `['resume', <id>]` when resuming, or empty for fresh), then spread into argv between the binary path and `--model`. The prior warning is removed. Codex's flag-style `--resume` was never accepted by the binary in the first place; the new shape matches what `codex resume --help` documents on Codex 0.130.
+
+Stale-id handling: if the tracked SESSION_ID no longer exists in Codex's session store, `codex resume` exits non-zero at startup and the tmux pane shows an error. SessionManager's respawn logic catches the dead pane, and the route handler can clear the stale resume id (same pattern PR #248 established for framework swaps clearing resume ids whose scheme no longer matches the new framework).
+
+In capability-matrix terms (from `specs/instar-foundations/required-primitives-inventory.md` once it lands on main), this shifts primitive #7 Session-resume on Codex from `partial ⚠️` to `native ✓`.
+
+## What to Tell Your User
+
+- "Codex sessions you've been chatting with now actually pick up where they left off after a restart. Before, restarts silently started a fresh session and lost the conversation thread."
+- "No action needed. Topics that were tracked with a Codex session id will resume the next time they restart."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Codex session resume | Automatic — when a topic has a tracked Codex session id, launch uses `codex resume <id>` as a subcommand |
+
+## Evidence
+
+The bug was reproducible: any Codex topic that had a tracked session id and got respawned (manually, via /restart, or via lifeline recovery) logged a `console.warn` about Codex resume being a subcommand and started fresh — the user's conversation history in that session was gone from Codex's view (Instar's topic history was still there, but the model lost continuity).
+
+Unit tests confirm the new argv shape:
+
+- `resume <id>` inserted at positions 1 and 2 of argv when `resumeSessionId` is set
+- No `resume` token in argv when `resumeSessionId` is absent (fresh launch unchanged)
+- Sandbox flags (`--sandbox`, `--ask-for-approval`, `--dangerously-bypass-approvals-and-sandbox`) preserved when resuming
+- Local-model flags (`--oss`, `--local-provider`) preserved when resuming
+- The flag-style `--resume` is never emitted (Codex doesn't accept it)
+
+Test file: `tests/unit/frameworkSessionLaunch.test.ts` (38/38 passing — 4 new tests in the codex-cli describe block, 1 prior test updated from "should-not-resume-because-not-supported" to "should-insert-subcommand"). Typecheck: clean.

package/upgrades/1.0.0.md

@@ -0,0 +1,165 @@
+# Upgrade Guide — v1.0.0 (Provider Portability release)
+
+<!-- bump: major -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## v1.0.0 headline (what this release IS)
+
+Instar is no longer locked to one AI provider. Every hot-path session
+(interactive, headless, pipe-mode, upgrade-notify, stall-recovery)
+routes through a framework-aware launch helper that supports Claude
+Code, OpenAI Codex, AND local models via Ollama / LM Studio (through
+Codex CLI's `--oss` passthrough). Operators flip a topic between
+frameworks via the `/route` slash command. Generic model tiers
+(`fast` / `balanced` / `capable`) map to each framework's preferred
+concrete model automatically.
+
+Spec 12 Rule 1 (Codex subscription-only path) lands in Phase A:
+adapter init emits a warning + telemetry when API-key auth is
+detected; full refusal is opt-in via `INSTAR_RULE1_ENFORCE=hard` for
+v1.0.0 and default in v1.1.
+
+Local-model adapter is shipped as a passthrough — `codex exec
+--oss --local-provider ollama --model llama3.2:latest` works
+end-to-end via Codex CLI 0.50.x. Recipe at `docs/local-model-recipe.md`.
+
+Existing Claude-only installs upgrade transparently: framework
+defaults to claude-code, no behavior change unless the operator opts
+into Codex or local-model routing.
+
+## What Changed
+
+Codex topics now round-trip end-to-end. Four follow-ups on the /route work below closed the live-test gaps that surfaced when the framework was switched on a real Telegram topic.
+
+First, `respawnSessionForTopic` now kills the existing tmux session before spawning a replacement. `SessionManager.spawnInteractiveSession` no-ops when a tmux session with the same name already exists — that's intentional for "reuse the agent that's already up" semantics, but it silently defeats a framework swap: the kill-and-respawn invariant the /route flow assumed wasn't there. Added the kill at the top of `respawnSessionForTopic` (idempotent — no-op when the session is already dead), so every framework swap, recovery respawn, and /restart path now gets a fresh process. Verified live: a `/route claude-code → codex-cli` swap on a topic with an active Claude tmux session now actually replaces it with a Codex one.
+
+Second, the per-topic resume-uuid is now cleared on framework swap inside the /route handler. The UUID was created under one framework's session-id scheme and is meaningless to the other (Claude UUIDs ≠ Codex session ids); without clearing it the new spawn's `--resume <id>` either logged a "starting fresh" warning (Codex) or attempted to attach to a non-existent session (Claude). The route handler now calls `_topicResumeMap.remove(topicId)` between the store update and the respawn.
+
+Third, codex spawns now request `gpt-5.3-codex` explicitly via `--model`. Codex CLI's default is `gpt-5.2-codex`, which OpenAI retired from ChatGPT-subscription auth on 2026-04-14 (Community thread 1378986). Without the flag, a spawn under a subscription account hits "The 'gpt-5.2-codex' model is not supported when using Codex with a ChatGPT account" on the first turn. Picked `gpt-5.3-codex` (the coding-specialist tier in `providers/adapters/openai-codex/models.ts`); API-key users can override per session via `~/.codex/config.toml` or `-c model=`.
+
+Fourth, codex spawns now use `--dangerously-bypass-approvals-and-sandbox` instead of the prior `--sandbox workspace-write --ask-for-approval never` pair. Claude's `--dangerously-skip-permissions` is one flag that means BOTH "no approval prompts" AND "no sandbox" — the parity flag on Codex is the bypass, not the flag-pair. The flag-pair left Codex's seatbelt sandbox running, which blocked the agent from reaching localhost (where the relay script ultimately posts) and from writing outside the project (which the relay needs for its outbox), so Codex sessions read AGENTS.md, attempted the relay, and got denied at the syscall level. `codexSandboxMode` callers still get the flag-pair form for the safer profile. Live-verified: Codex now reaches `.claude/scripts/telegram-reply.sh`, calls instar's local server, and round-trips messages back to the Telegram topic.
+
+Fifth, `SessionManager.rawInject` is now framework-aware. Codex's TUI takes longer than Claude's to commit a bracketed paste into its input state, and silently discards a single Enter that arrives during that window — observed live as messages stacking up in Codex's input box without ever submitting. The injector now reads the spawned session's `INSTAR_FRAMEWORK` from its tmux env (cached, single lookup per session), and for `codex-cli` waits 1.5s after the paste end (vs 0.5s for Claude) and sends Enter twice with a 300ms gap. The second Enter is a harmless no-op against an empty buffer if the first one landed. `clearSessionFrameworkCache(name)` is exposed so callers killing-and-respawning a tmux name under a different framework (e.g., the /route flow) can invalidate the cache; `respawnSessionForTopic` calls it.
+
+Sixth (closes the legacy-install gap): `spawnSessionForTopic` now calls `ensureFrameworkIdentityFile` before every spawn — a new idempotent helper in `IdentityRenderer` that ensures the framework's shadow file (AGENTS.md for codex-cli, CLAUDE.md for claude-code) exists at the project root. When `.instar/AGENT.md` exists, it renders from there; when only a legacy shadow exists (older installs that authored CLAUDE.md directly without AGENT.md), it bootstraps AGENT.md from the legacy shadow first, then renders. Idempotent — no-op when the target shadow already exists, so the per-spawn cost is one stat call. Closes the gap that required dropping AGENTS.md by hand for the live test. 6 new unit tests.
+
+/route slash-command landed: users can now flip a Telegram topic between Claude Code and Codex via a conversational command. `/route` or `/route status` shows the current framework; `/route claude-code` or `/route codex-cli` switches and respawns the topic's session via the existing TopicMemory-bootstrapping respawn flow. State persists in `<stateDir>/state/topic-frameworks.json` (atomic writes; separate from the operator-edited `topicFrameworks` in config.json so the two write paths don't race). New `TopicFrameworksStore` tolerates corrupt state files at boot — falls back to config defaults rather than crashing. 9 new store tests + 89 touched-area tests pass. Per Justin's clarified design model: the user-facing choice is Claude Code vs Codex; the SDK-credit-vs-subscription distinction inside "Claude Code" is invisible (Phase 5c cost-router handles it automatically when wired in a follow-up).
+
+Tier 1.A (spawnInteractiveSession framework dispatch + per-topic override) landed: the foundational Telegram-driven session spawn path no longer hardcodes Claude's CLI flags. New `src/core/frameworkSessionLaunch.ts` carries per-framework builders that return `{ argv, envOverrides }`; SessionManager dispatches to the right builder based on a new optional `framework` parameter. New `InstarConfig.topicFrameworks` map (`{ "9984": "claude-code", "9985": "codex-cli" }`) lets operators flip a single topic to a different framework without changing the agent's overall framework. `spawnSessionForTopic` and `respawnSessionForTopic` consult the per-topic map via a `resolveTopicFramework(topicId)` helper. `SessionManagerConfig.frameworkBinaryPaths` populated from detection at load time so the dispatcher picks the right binary. Existing Claude callers behave identically. The Agent SDK spawn mode is deferred — needs a different shape than tmux'd CLIs. 12 new launch-builder tests; 181 touched-area tests still pass.
+
+Tier 2.B+ (SessionWatchdog framework-aware PID resolution) landed: the watchdog's `getClaudePid` resolved the in-pane CLI process by matching `^claude$` / `/claude$` directly, so for Codex installs it returned null and the watchdog silently no-opped on every Codex session. New `getFrameworkPid` walks `listProcessSignals()` (reusing Tier 2.C's framework process signals) and matches both bare-name (`claude`, `codex`) and path-tail forms, then falls back to a multi-needle egrep on the pane's child processes. The 65 existing watchdog tests all pass.
+
+Tier 2.E (subsystem framework-aware intelligence) landed: server-boot smoke test of `INSTAR_FRAMEWORK=codex-cli` revealed that three subsystems were still constructing their own `ClaudeCliIntelligenceProvider` rather than reusing the framework-aware `sharedIntelligence` singleton: RelationshipManager (identity resolution), TopicSummarizer (session-completion summaries), and JobReflector (via `instar reflect`). All three now consult `sharedIntelligence` first and fall back to a Claude provider only when sharedIntelligence couldn't be built. Boot log now reports `Relationships loaded: 0 tracked (LLM-supervised (Codex CLI))` instead of always claiming Claude. No interface changes, no new tests (call-site re-pointer to an already-tested singleton).
+
+Provider-portability v1.0.0 spawn-path closure: every remaining hot-path Claude hardcode shipped. New `buildHeadlessLaunch(framework, options)` companion to the existing `buildInteractiveLaunch` — same shape, same exhaustiveness check, same envOverrides contract. `SessionManager.spawnSession` (the headless `-p` prompt path) now routes through it with a per-call `framework` override and reads its binary from `frameworkBinaryPaths[framework]`. `PipeSessionSpawner`'s three direct `claude -p` callsites are gone: `classifyIntent` and `summarizeThreadHistory` accept an `IntelligenceProvider` (fail-closed to interactive/unavailable when none is wired — safer than the old silent shell-exec failure); `spawn()` uses `buildHeadlessLaunch` + `$(< "$file")` substitution so the prompt stays off the command line (no leak via `ps`). Env scrub now covers both `ANTHROPIC_API_KEY` AND `OPENAI_API_KEY` (Spec 12 Rule 1a extended to the pipe spawn). server.ts wires the pipe spawner with the resolved framework + sharedIntelligence. 11 new pipe-portability tests + buildHeadlessLaunch test coverage; 74/74 unit tests across the touched files green.
+
+Provider-portability v1.0.0 tier-vocabulary unification: cross-framework generic tiers (`fast`|`balanced`|`capable`) are now the canonical model vocabulary. New `resolveModelForFramework(framework, modelOrTier)` helper maps the generic tiers to each framework's preferred concrete model (`fast`→`haiku`/`gpt-5.2`, `balanced`→`sonnet`/`gpt-5.3-codex`, `capable`→`opus`/`gpt-5.4`). Legacy Claude tier names map cleanly to Codex equivalents so unported callsites don't crash; raw model ids pass through verbatim. The Codex builder's hardcoded `'gpt-5.3-codex'` is now a `SessionManagerConfig.frameworkDefaultModels['codex-cli']` lookup — operators can override per agent without code changes. `UpgradeNotifyManager.MODEL_CHAIN` switched from Claude-only `['haiku','sonnet']` to generic `['fast','balanced']`; the spawn callback widened to accept generic tiers. `/sessions/spawn` route accepts a `framework` field and a framework-aware model whitelist that rejects Claude-only names when `framework=codex-cli` (and vice versa). `StallTriageNurse` model normalization is now framework-aware: Codex agents get `gpt-5.3-codex` for the default `balanced` tier instead of `claude-sonnet-4-6`. 5 new tier-resolution tests + 197/197 unit tests across 8 touched files green.
+
+Tier 4.C release blocker (Codex non-git directory fix): the `CodexCliIntelligenceProvider` was silently failing for every Codex-based agent whose state directory wasn't a git checkout. Codex CLI refused to run with `--cd <non-git-dir>` and the resulting error was masked downstream as `taskPattern: "unclassified"` (the classifier's catch-all). Added `--skip-git-repo-check` to the `codex exec` invocation; these reviewer/sentinel/canary calls don't depend on the cwd being a trusted git repo. Surfaced and verified via end-to-end smoke test (`INSTAR_FRAMEWORK=codex-cli node dist/cli.js route "refactor python helper"`) that previously produced `auto-defaulted-unclassified` in 0.8s; now produces `code-refactor-python` / `auto-defaulted-no-topic` in ~4s. 5 new regression tests use a fake codex script to assert the exact spawn-arg shape.
+
+## Evidence
+
+**Codex non-git directory fix** — reproduced and verified.
+
+Before (broken):
+```
+$ INSTAR_FRAMEWORK=codex-cli node dist/cli.js route "refactor this old python helper to use type hints" --dir /tmp/codex-smoke-2 --json
+{
+  "framework": "claude-code",
+  "model": "opus-4.7",
+  "taskPattern": "unclassified",
+  "source": "auto-defaulted-unclassified",
+  ...
+}
+# Internal Codex error visible only on direct provider call:
+#   Codex CLI error: Command failed: /Users/.../bin/codex exec --model gpt-5.2 --sandbox read-only --cd /tmp/codex-smoke-2/.instar ...
+#   Not inside a trusted directory and --skip-git-repo-check was not specified.
+```
+
+After:
+```
+$ INSTAR_FRAMEWORK=codex-cli node dist/cli.js route "refactor this old python helper to use type hints" --dir /tmp/codex-smoke-2 --json
+{
+  "framework": "claude-code",
+  "model": "opus-4.7",
+  "taskPattern": "code-refactor-python",
+  "source": "auto-defaulted-no-topic",
+  ...
+}
+```
+
+Tier 2.C (OrphanProcessReaper framework awareness) landed: the orphan-process sentinel no longer hardcodes Claude's binary patterns or its `grep -i '[c]laude'` prefilter. New `src/monitoring/frameworkProcessSignals.ts` exposes per-framework `psGrepNeedle`, `binaryPattern`, `nodePattern`, exclusion list, and display name; the reaper builds a single `ps … | egrep …` over every framework's needle and tags each process with the matched framework via `matchProcessSignal`. `FrameworkProcess` is the new canonical type (Claude/Codex/etc.); `ClaudeProcess` lives on as a deprecated alias for one release cycle. External-process Telegram alerts now group counts by framework display name. Orphan Codex processes are now detected and cleaned identically to orphan Claude processes. Also rewrote one orphaned `StallTriageNurse` test that asserted on the Rule-2-removed direct-API fallback; the replacement asserts the actual post-Rule-2 heuristic-fallback contract. 24 new signal tests + 200 existing tests pass.
+
+Tier 2.B (StallTriageNurse framework awareness) landed: the stall-detection sentinel's heuristic pre-filter no longer hardcodes Claude Code's tool-call regex and spinner glyphs. New `src/monitoring/frameworkActivitySignals.ts` exposes per-framework activity signatures (`toolCallOrSpinner`, `escapeToInterrupt`, `runningIndicator`, plus a prompt-signatures line injected into the LLM system prompt). The nurse reads `config.framework` from `StallTriageConfig` (defaulting to claude-code for backwards-compat), and `server.ts` threads the resolved `INSTAR_FRAMEWORK` value into the construction site. Previously the shell-prompt restart heuristic would false-fire on a healthy Codex pane (no Claude tokens → "framework wrapper has exited"); now it correctly recognizes Codex tool tokens. 22 new tests (16 signal-module + 6 framework-aware heuristics).
+
+CoherenceReviewer subclasses and CoherenceGate dropped the unused `apiKey` constructor parameter — dead since the Rule 2 path-constraint lockdown removed the direct-Anthropic-API fallback. Reviewer LLM calls already route exclusively through the IntelligenceProvider; the key was being stored but never read.
+
+CoherenceGate now requires an IntelligenceProvider. When none is wired, the response review pipeline is disabled with a warning instead of attempting a raw API fallback.
+
+Internal-only API change: external code that constructs CoherenceGate directly must drop `apiKey` from the options bag and supply `intelligence`.
+
+The anthropic-interactive-pool adapter now accepts an optional `llmFallback` in its config. The empty-prompt canary (Rule 3 detector for the pool's idle signal) had a tested LLM-fallback contract but no application-layer wiring — that's now plumbed end-to-end. Adapter clients can opt in by passing `buildCanaryLlmFallback(intelligence)`; omitting it preserves deterministic-only behavior.
+
+Phase 5c shipped: `CostAwareRoutingPolicy` and `CostStateTracker` in `src/providers/costAwareRouting.ts`. The policy implements the path-constraints "Routing default" (drain SDK credit pot while above the 10% safety margin, switch to subscription floor when at or below). The tracker emits `CostStateSnapshot` objects with a `isMaterialShift` helper Phase 5b consumes to decide when to re-ask the user. Pure additive infrastructure — not yet wired into the runtime; that wiring lands with Phase 5b implementation. 23 unit tests cover every row of the decision matrix and every material-shift category.
+
+Phase 5b.1 shipped: `PreferenceStore` (sqlite-backed cache of framework+model picks keyed by user × task pattern) and `TriggerGate` (pure-function decision logic implementing Phase 5b's three-trigger rule with priority ordering). Both live under `src/providers/uxConfirm/`. The remaining Phase 5b components — TaskClassifier, TelegramConfirmer, OverrideDetector, and the FrameworkModelRouter composition root — land in subsequent slices.
+
+Phase 5b.2 shipped: `TaskClassifier` and `OverrideDetector` — both fast-tier IntelligenceProvider classifiers under `src/providers/uxConfirm/`. The classifier maps a task prompt to a stable kebab-case slug (the cache key for preferences). The detector spots routing overrides in free-text messages ("use Gemini for this one") via LLM, not regex, per the "intelligence over string matching" rule. Both fail-safe on errors — unclassified slug or no-override outcome — so the UX never silently auto-uses a wrong pick. 33 new unit tests pass (13 classifier + 20 detector, including the 8 phrasing variants the spec required).
+
+Phase 5b.3 shipped: `TelegramConfirmer` — the blocking suggest-and-confirm round-trip. Sends the structured prompt via a thin `ConfirmationTransport` interface (testable without real Telegram), blocks on next reply with timeout, parses replies through four deterministic shorthand paths (`ok|c|👍|no|once|/route reset`) before falling through to the LLM-backed `OverrideDetector` for free-text. Returns a discriminated `ConfirmationResult` (`confirmed | overridden | reset | default-no-reply`). 30 new tests; cumulative uxConfirm coverage now 86 tests.
+
+Phase 5b.4 shipped: `FrameworkModelRouter` — the composition root that ties every Phase 5b component into the full flow. Returns a structured `RouteResult` with eight distinct `source` values covering every outcome (cached-silent, confirmed, confirmed-one-shot, overridden-this-task, overridden-this-pattern, reset-defaulted, auto-defaulted-no-topic, auto-defaulted-no-reply, auto-defaulted-unclassified). Cache writes are scoped strictly to user-confirmed paths. The `CatalogProvider` interface abstracts over Phase 5a artifacts so the router doesn't read markdown directly. 13 router tests; cumulative uxConfirm coverage 99 tests.
+
+Phase 5b.5.c shipped: `instar route <task...>` CLI subcommand — a thin composition root that wires every Phase 5b component (TaskClassifier, OverrideDetector, PreferenceStore, StaticCatalogProvider, CostStateTracker, TelegramConfirmer, FrameworkModelRouter) and runs a single classification. Forces `telegramTopicId: null` so the CLI path is deterministic (no-topic → catalog default). Lets Justin exercise the end-to-end Phase 5b flow against his real IntelligenceProvider (Claude or Codex per `INSTAR_FRAMEWORK`) without standing up the full HTTP/Telegram wiring. AgentServer integration deferred — that wiring touches the massive injected-dependencies constructor and is tracked separately.
+
+Phase 5b.5.b shipped: `TelegramConfirmationTransport` — bridges the push-based `MessagingAdapter.onMessage` contract to the pull-based `ConfirmationTransport.awaitReply` contract Phase 5b.3 requires. Per-topic waiter queue with timeout; supersession (new awaitReply on same topic resolves prior with null); drop-on-no-waiter for stale replies; shutdown resolves all pending. Composable via `MinimalMessagingAdapter` + caller-supplied `topicFromInbound` / `outboundForTopic` — same class drives Slack/iMessage/etc. when those land. 9 new tests against a fake adapter; cumulative uxConfirm coverage 124 tests.
+
+Phase 5b.5.a shipped: `StaticCatalogProvider` — hand-curated CatalogProvider implementation. 20 task-pattern defaults derived from the Phase 5a catalogs (code-generation/refactor/debug → Opus 4.7; web-research → Sonnet 4.6; summarize/draft/shell → Haiku 4.5; etc.) plus per-(framework, model) confidence baselines and a `CATALOG_VERSION` string that drives Phase 5b's re-ask trigger. Hand-curated rather than markdown-parsed: deliberate updates when the catalog moves, not silent drift from regex breakage. 16 new tests; cumulative uxConfirm coverage 115 tests.
+
+Tier 0 release blocker fixed: stripped a hardcoded developer-specific path (`/Users/justin/.asdf/installs/nodejs/22.18.0/bin/codex`) from the Codex adapter default config. Replaced with a new framework-agnostic `detectFrameworkBinary(name)` helper that searches install locations, npm-global, nvm-managed, and PATH for any of eight known framework binaries (claude, codex, gemini, aider, goose, cursor-cli, opencode, plandex). Includes a source-level regression test that fails if any future commit re-introduces the asdf hardcode.
+
+Tier 1.B (multi-provider credentials) landed: new `ProviderCredentialKind` + `ProviderCredential` types, new `SessionManagerConfig.credentials: { [providerId]: ... }` field with legacy `anthropicApiKey` / `anthropicBaseUrl` automatically migrated at load time. New helpers `getProviderCredential(config, providerId)` and `buildProviderEnvFlags(providerId, cred)` give code paths a clean way to ask "do I have a credential for X" and "what env vars do I inject when spawning a subprocess for provider X." SessionManager spawn paths are unchanged in this slice — they still read the legacy field; migration to the helper is a follow-up. 14 tests cover migration, kind detection, baseUrl propagation, lookup fallback, and env-flag building for anthropic/openai/google + unknown-provider safe-no-op.
+
+Tier 1.C (Codex intelligence provider) landed: new `CodexCliIntelligenceProvider` sibling of `ClaudeCliIntelligenceProvider`. Routes evaluate() calls through `codex exec` with tier→model mapping reused from the Codex adapter. Plus a `buildIntelligenceProvider({ framework })` factory that picks the right implementation at startup, and a `frameworkFromEnv()` parser for the new `INSTAR_FRAMEWORK` env var (accepts `claude-code` / `claude` / `codex-cli` / `codex` case-insensitive). Until now `ClaudeCliIntelligenceProvider` was the ONLY implementation, so every reviewer/sentinel/canary ran `claude -p` exclusively — "supports Codex" was a promise we couldn't keep. 10 tests cover framework selection, binary detection fallback, env-var parsing.
+
+Tier 1.D (identity-file rendering) landed: AGENT.md is now the canonical source of truth for an agent's identity. New `IdentityRenderer` module reads `.instar/AGENT.md` and writes framework-specific shadow files (CLAUDE.md for Claude Code, AGENTS.md for Codex, GEMINI.md for Gemini) with an auto-generation banner warning against hand-editing. ProjectMapper lookup priority flipped to AGENT.md first, CLAUDE.md fallback (existing installs keep working). Migration path: `bootstrapAgentMdFromShadow` reads legacy CLAUDE.md content, strips banner, writes canonical AGENT.md. 16 tests cover render, banner content, framework subset, source fallback, throw-on-missing, framework detection, and migration bootstrap.
+
+Tier 2.A (framework-aware boot prerequisite) landed: `Config.load()` no longer throws "Claude CLI not found" unconditionally. New pure helpers `resolveConfiguredFramework()` (picks active framework from config / INSTAR_FRAMEWORK env / default claude-code) and `checkFrameworkPrerequisite()` (validates the configured framework's binary is installed) decouple boot logic from Claude. Codex-cli installs now boot cleanly with only the codex binary present. Error messages are framework-specific with the right install command. New `sessions.framework` config field + `INSTAR_FRAMEWORK` env var (accepts claude-code/claude/codex-cli/codex). 11 tests cover every framework × binary-presence combination.
+
+## What to Tell Your User
+
+- **You can pick which AI I run on per topic now.** Tell me "switch this topic to Codex" or "switch this topic to Claude" and I'll respawn with the other framework. The default stays the same as before — you choose only when you want a change.
+- **I can run a local model for sensitive work.** If you have Ollama installed on your machine, tell me "use the local model for this topic" and your prompts never leave your machine. Best for routine work; complex coding still wants a frontier model.
+- **No surprises if you upgrade in place.** Your existing agents keep working exactly as they did. The new portability paths only activate when you ask for them.
+- **You may see a one-time warning at startup** if your machine has an OpenAI API key set in its environment. That's a heads-up — I'll explain why and how to switch to the subscription path. It's informational only; nothing breaks.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Per-topic framework swap (Claude vs Codex) | Ask the agent: "switch this topic to Codex" |
+| Per-topic local model (Ollama) | Ask the agent: "use the local model for this topic" |
+| Cross-framework model tiers (fast, balanced, capable) | Automatic — the right concrete model is picked per framework |
+| Codex subscription-path enforcement (Spec 12 Rule 1) | Automatic warning when an API key is present; full refusal opt-in for early adopters |
+| Existing-install upgrade safety | Automatic — framework defaults to Claude; no behavior change unless you choose |
+
+## Evidence
+
+<!-- REQUIRED if this release claims to fix a bug. -->
+<!-- Unit tests passing is NOT evidence. Provide ONE of: -->
+<!--   (a) Reproduction steps + observed before/after on a live system. -->
+<!--       Include log excerpts, observed command output, or behavior -->
+<!--       description. Make it specific enough that a future reader can -->
+<!--       re-run it and see the same thing. -->
+<!--   (b) "Not reproducible in dev — [concrete reason]" if the failure -->
+<!--       mode truly can't be exercised locally (race conditions, -->
+<!--       event-driven paths requiring external signals, etc). -->
+<!--                                                                 -->
+<!-- If this release doesn't claim a bug fix (pure feature / refactor), -->
+<!-- leave this section blank or delete it — it's only enforced when -->
+<!-- "What Changed" describes a fix. -->
+
+[Describe reproduction + verified fix, OR "Not reproducible in dev — [concrete reason]"]

package/upgrades/side-effects/1.0.0.md

@@ -0,0 +1,75 @@
+# Side-effects review — v1.0.0 release rollup (Provider Portability)
+
+**Version / slug:** `1.0.0` (release rollup)
+**Date:** `2026-05-18`
+**Author:** Echo
+**Second-pass reviewer:** self-review — every constituent change shipped through its own /instar-dev cycle with its own artifact, listed below.
+**Driving spec:** `specs/provider-portability/README.md` (Phase 8 release cut).
+
+## Summary of the v1.0.0 release
+
+This is the rollup artifact for v1.0.0 — the first portable Instar release. Provider portability ends Anthropic-only lock-in. Every hot-path session (interactive, headless, pipe-mode, upgrade-notify, stall-recovery) now routes through a framework-aware launch helper that supports Claude Code, OpenAI Codex, AND local models via Codex CLI's `--oss --local-provider` passthrough.
+
+The release closes nine work tracks across multiple autonomous cycles. Each track shipped its own /instar-dev cycle with its own side-effects artifact:
+
+| Track | Slug | Date |
+|---|---|---|
+| Spec 12 Rule 1a env scrubbing | `codex-env-scrubbing` (prior) | 2026-05-17 |
+| Phase 5b/5c routing | various Phase 5 artifacts | 2026-05-17 |
+| Spawn-path closure (buildHeadlessLaunch + PipeSessionSpawner) | `portability-headless-launch-helper` | 2026-05-18 |
+| Generic tier routing + /sessions/spawn whitelist + StallTriageNurse normalization | `portability-generic-tier-routing` | 2026-05-18 |
+| Codex Rule 1 Phase A + Phase B opt-in + drift gate | `codex-rule1-phase-a-and-b-groundwork` | 2026-05-18 |
+| Phase 6 local-model adapter via Codex --oss | `local-model-codex-oss` | 2026-05-18 |
+| Phase 7 migration entry | `migrate-provider-portability` | 2026-05-18 |
+| Sentinel + monitoring cross-port | `sentinel-monitoring-cross-port` | 2026-05-18 |
+
+## What changes for end users
+
+- **No-op for Claude-only installs.** Framework defaults to `claude-code`. Existing topics keep working. No config required.
+- **Per-topic framework swap.** `/route codex-cli` flips a topic; `/route claude-code` flips it back. Per-topic config in `topicFrameworks` map.
+- **Per-topic local model.** With Ollama installed locally, set `topicCodexLocalProvider` + `topicCodexLocalModel` in config and restart. Recipe at `docs/local-model-recipe.md`.
+- **Codex API-key warning.** Agents that have `OPENAI_API_KEY` in env or API-key auth in `~/.codex/auth.json` get a Spec 12 Rule 1 warning at adapter init. No behavior change — the warning is informational in v1.0.0 Phase A. Lock down early via `INSTAR_RULE1_ENFORCE=hard` env var. Escape hatch `INSTAR_DISABLE_RULE1_OPENAI=1` sunsets 2026-12-01.
+
+## Decision-point inventory (release-level)
+
+- **Phase A as default** (not Phase B) — back-compat for existing installs.
+- **Local-model as passthrough** (not new adapter) — Codex CLI handles the OpenAI-API translation; zero translation code in Instar.
+- **No silent framework-default flip** — operator opts in via `/route` or config.
+- **Lifeline doctor stays Claude-only** — Codex equivalents require their own design pass; documented residual.
+- **Setup wizard stays Claude-only** — Claude Code's skill system is upstream territory.
+
+## Signal vs authority (release-level)
+
+- All framework dispatch helpers (`frameworkSessionLaunch`, `resolveModelForFramework`, `resolveTopicFramework`) are pure functions — signal.
+- `/sessions/spawn`'s framework-aware whitelist, the Codex Rule 1 validator at adapter init, and `PostUpdateMigrator.migrateProviderPortability`'s marker are the authorities.
+- Sentinels (InstructionsVerifier, PromptGate, StallTriageNurse) are signal layers feeding the existing authority layer above them.
+
+## Over-block / under-block analysis (release-level)
+
+**Over-block:** None at the release level. Each individual artifact analyzed its own scope and confirmed no new false-positive blocks.
+
+**Under-block:** Documented residuals (Lifeline doctor + setup wizard under Codex; `OPENAI_BASE_URL` HMAC approval flow). Each is honest scope, not silent gap.
+
+## Level-of-abstraction fit
+
+The release introduces no new architectural layers. It populates the existing provider-substrate layer (Phase 2 interfaces) with one new framework (Codex) and one new model class (local). Sentinels gain a `framework?` field; spawn paths gain a `framework` + `codexLocalProvider` option. No cross-layer leaks.
+
+## Interactions
+
+- Cost-aware routing (Phase 5c) is orthogonal to local-model passthrough — `CostAwareRoutingPolicy` ignores local sessions (no credit pot). Future Phase 5d work could integrate.
+- Spec 12 Rule 1 validator and Rule 1a env-scrub cooperate at adapter init + spawn time.
+- All sentinels coexist; framework-aware defaults degrade gracefully (cross-framework fallback when no hint).
+
+## Rollback cost
+
+Per-cycle revert is cheap (each cycle is a separate commit with its own artifact). Full v1.0.0 rollback to 0.28.76 requires reverting the release-cut commit + the per-cycle commits; no schema migration to undo, no on-disk state changes beyond the (benign) `_instar_migrations` marker in agents that ran `instar update` against v1.0.0.
+
+## Verification
+
+- `npx tsc --noEmit` — clean.
+- `npm run lint` — clean (includes drift gate).
+- Per-cycle unit + integration tests — all green at commit time.
+- 12/12 v1.0.0 scenarios green via injection mode against updated deep-signal.
+- Live Codex spawn round-trip succeeded on deep-signal (`/sessions/spawn` with `framework: codex-cli`).
+- Live Codex --oss + Ollama smoke succeeded (`codex exec --oss --local-provider ollama --model llama3.2:latest --json` returned PONG in ~3s).
+- Real-Telegram-loop verification requires provisioning a separate driver bot — documented as setup step, not a behavior gap (polling-health scenario #11 covers the network leg without that dependency).

package/upgrades/side-effects/canary-llm-fallback-wiring.md

@@ -0,0 +1,66 @@
+# Side-effects review — wire canary LLM fallback into the application layer
+
+**Version / slug:** `canary-llm-fallback-wiring`
+**Date:** `2026-05-15`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (additive plumbing of an existing, tested fallback function into a previously-unused field on the pool config)
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md` (Rule 3 — state-detection robustness; the empty-prompt canary IS the Rule 3 self-test for the pool's idle detector)
+
+## Summary of the change
+
+Tasks #16 (canary LLM fallback) and the unit tests under `emptyPromptCanary-llmFallback.test.ts` established the `CanaryLlmFallback` contract and verified the canary calls it correctly when deterministic re-derivation fails. Until this change, that fallback was never threaded into the runtime — both call sites of `runEmptyPromptCanary()` inside `pool.ts` passed only the three required positional arguments and omitted the optional `options.llmFallback`. The fallback existed but was structurally dead at runtime.
+
+This change wires the path end-to-end:
+
+- `InteractivePoolConfig` grows an optional `llmFallback?: CanaryLlmFallback` field.
+- Both `pool.ts` canary call sites pass `this.config.llmFallback` through to `runEmptyPromptCanary`.
+- The adapter entry point exposes `buildCanaryLlmFallback(intelligence)` — a small helper that turns an `IntelligenceProvider` into a `CanaryLlmFallback` by sending a narrowly-scoped "is this pane at a completed prompt?" prompt to the fast tier (Haiku-class), parsing the single-word verdict, and treating provider errors as `'error'` (the canary's recipe-conservative outcome).
+
+Application-layer wiring is now `createAnthropicInteractivePoolAdapter({ ..., llmFallback: buildCanaryLlmFallback(intelligence) })`. Omitting the field leaves the canary deterministic-only — a failed re-derivation surfaces as a hard fail, exactly as it did before this change.
+
+Files touched:
+- `src/providers/adapters/anthropic-interactive-pool/config.ts` — added optional `llmFallback` field + import of the `CanaryLlmFallback` type.
+- `src/providers/adapters/anthropic-interactive-pool/pool.ts` — both `runEmptyPromptCanary` call sites now pass `{ llmFallback: this.config.llmFallback }`.
+- `src/providers/adapters/anthropic-interactive-pool/index.ts` — new exported `buildCanaryLlmFallback` helper.
+- `tests/unit/providers/adapters/anthropic-interactive-pool/buildCanaryLlmFallback.test.ts` — new, 8 cases covering parsing variants, error fail-safe, fast-tier routing budget, and bottom-30-line windowing of the prompt.
+
+## Decision-point inventory
+
+- **Canary self-heal verdict** — `pass-through`. The canary itself still decides what to do with the fallback verdict (see `emptyPromptCanary.ts` step 9). This change only ensures the fallback is reachable; the canary's existing decision logic is unchanged.
+- **Application-layer config wiring** — `add`. Callers of `createAnthropicInteractivePoolAdapter` may now opt in to the LLM fallback by passing `llmFallback: buildCanaryLlmFallback(intelligence)`. Default behavior (no fallback) is unchanged.
+- No new gates, no new authorities, no new blocking surfaces.
+
+## Signal vs authority
+
+The fallback is a signal producer (it returns one of `'complete' | 'not-complete' | 'error'`). The canary remains the only authority that decides what those signals mean for pool health. The helper does not gate anything — it returns a verdict that the existing canary logic interprets. Provider errors collapse silently to `'error'`, which the canary already treats as the conservative "do not trust" path.
+
+## Over-block / under-block analysis
+
+- **Over-block:** None. A misbehaving LLM that returns junk falls into the `'error'` branch, which the canary already treats as conservative-fail (same behavior as if no fallback were configured). The fallback can never cause a healthier verdict than the deterministic path would have produced when it succeeded.
+- **Under-block:** Possible. If the canary's deterministic re-derivation has failed AND the LLM lies about what's on the pane (says "complete" when Claude Code is actually mid-generation), the canary will continue serving with a stale signature for one cycle longer. This is bounded by `canaryIntervalMs` (default 1h) — the next cycle re-runs the deterministic path. The risk is documented in `emptyPromptCanary.ts:218-264` as the explicit cost of keeping the pool operational rather than hard-failing on every UI shift.
+
+## Level-of-abstraction fit
+
+The helper lives in the adapter entry-point module because it bridges two abstractions: the pool's internal `CanaryLlmFallback` shape (defined in the canary module) and the application layer's `IntelligenceProvider` (defined in `core/types.ts`). Putting the bridge in `index.ts` keeps both inner modules ignorant of the application-layer LLM abstraction.
+
+## Interactions
+
+- **Existing canary tests** in `emptyPromptCanary-llmFallback.test.ts` still pass — they construct their own `vi.fn()` fallback and don't depend on the config wiring.
+- **`InteractivePool.runScheduledCanary()`** and **`InteractivePool.spawnOne()`** are the only two consumers of the threaded value. Both pass it through identically.
+- **Adapter factory tests** don't yet assert on `llmFallback` because no production wiring uses it yet. When the runtime is wired (a later phase), an integration test will exercise the live path.
+
+## External surfaces
+
+- `InteractivePoolConfig.llmFallback` — new optional field. Backwards-compatible (omitting it preserves prior behavior).
+- `buildCanaryLlmFallback(intelligence)` — new exported helper from `anthropic-interactive-pool/index.ts`.
+- No new endpoint, no new CLI command.
+
+## Rollback cost
+
+Trivial. `git revert` restores three source files + removes the new test. No persistent state changes. Pre-existing canary behavior is unchanged.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/providers/adapters/anthropic-interactive-pool/` — 40/40 pass (8 new from buildCanaryLlmFallback.test.ts; 32 pre-existing unchanged).
+- The bottom-30-line windowing assertion guards against the prompt growing unboundedly with pane history — a regression that would silently inflate per-canary token cost.

package/upgrades/side-effects/codex-rule1-phase-a-and-b-groundwork.md

@@ -0,0 +1,83 @@
+# Side-effects review — Codex Rule 1 Phase A + structural Phase B groundwork
+
+**Version / slug:** `codex-rule1-phase-a-and-b-groundwork`
+**Date:** `2026-05-18`
+**Author:** Echo
+**Second-pass reviewer:** self-review — 23 new unit tests green; typecheck clean; drift gate active and passing.
+**Driving spec:** `specs/provider-portability/12-openai-path-constraints.md` (approved 2026-05-17)
+
+## Summary of the change
+
+Lands spec 12 Rule 1 enforcement for the openai-codex adapter. Phase A behavior is the **default** for v1.0.0 (warning + telemetry, no behavior change for existing installs); Phase B behavior is **opt-in via env** (`INSTAR_RULE1_ENFORCE=hard`) so deployments can elect to refuse early.
+
+1. **`src/providers/adapters/openai-codex/config.ts`** — rewritten:
+   - Stale "Agent SDK credit pot analog" comment block replaced with a reference to spec 12 Rule 1 (correct framing: API-key auth is FORBIDDEN, not "acceptable").
+   - `configFromEnv` no longer reads `OPENAI_API_KEY` into config. The `apiKey: env['OPENAI_API_KEY']` line is gone.
+   - `OpenAiCodexConfig.apiKey` field is now annotated `@deprecated` + `@internal` so external callers see TypeScript/IDE warnings while their code keeps compiling (Phase A back-compat).
+
+2. **`src/providers/adapters/openai-codex/credentials.ts`** (new) — Rule 1 validator. Detects API-key auth via env var OR `~/.codex/auth.json` shape. Returns structured error codes:
+   - `CODEX_AUTH_APIKEY_DETECTED` (security_violation class)
+   - `CODEX_KILLSWITCH_EXPIRED` (security_violation; escape hatch past sunset)
+   - plus FILE_MISSING / FILE_UNREADABLE / FILE_MALFORMED / OAUTH_REFRESH_FAILED / UNKNOWN_FAILURE codes per spec 12.
+   
+   Enforcement modes:
+   - `warn` (default for v1.0.0 Phase A) — emit structured warning to stderr, write telemetry to `.instar/security.jsonl`, do not refuse.
+   - `hard` (opt-in via `INSTAR_RULE1_ENFORCE=hard`) — adapter init throws `AuthError`.
+   - `disabled` (escape hatch via `INSTAR_DISABLE_RULE1_OPENAI=1`) — suppresses warning entirely until sunset.
+   
+   Hard sunset constant `RULE1_KILLSWITCH_SUNSET_DATE = '2026-12-01'`. After that date the escape hatch is ignored.
+
+3. **`src/providers/adapters/openai-codex/index.ts`** — wires `checkAndWarn` into `createOpenAiCodexAdapter`. Runs at adapter construction; in `hard` mode throws `AuthError`; in `warn` mode logs + appends telemetry and returns. Telemetry includes `stateDir` when caller provides `defaultWorkingDirectory` (the convention used by the rest of the adapter).
+
+4. **`scripts/check-codex-rule1-drift.js`** (new) — CI drift-detection gate. Fails the build when `config.ts` regresses:
+   - Forbidden string `"Agent SDK credit pot analog"` reappears.
+   - `apiKey: env['OPENAI_API_KEY']` (or variants) reappears in `configFromEnv`.
+   - `apiKey` field on `OpenAiCodexConfig` is missing `@deprecated` AND `@internal` tags (Phase A) AND isn't narrowed to `never` (Phase B+).
+   
+   Wired into `npm run lint` so every commit + push runs it.
+
+5. **`tests/unit/providers/adapters/openai-codex/credentialsRule1.test.ts`** (new) — 23 cases covering: configFromEnv no-read; env detection; auth-file detection (api_key + apiKey field variants); enforcement mode resolution; killswitch sunset; checkAndWarn warn/silent/telemetry branches.
+
+## Decision-point inventory
+
+- **Phase A as default for v1.0.0** — `add`. Existing installs that have `OPENAI_API_KEY` set don't break the moment they upgrade — they get a visible warning and a telemetry event. The operator decides when to flip the env to `hard`.
+- **`INSTAR_RULE1_ENFORCE=hard` opt-in** — `add`. Lets deployments that have ALREADY moved to subscription auth lock the rule down early, before v1.1's default flip.
+- **`INSTAR_DISABLE_RULE1_OPENAI=1` escape hatch** — `add`. Required by spec 12 for the migration window. Sunsets on hardcoded date.
+- **Drift gate at lint time, not just CI** — `extend`. Runs in `npm run lint` which fires on every pre-commit. Catches local regressions before push.
+- **`apiKey` field stays as `string` in Phase A** — deliberate. Narrowing to `never` immediately would break the type for any third-party consumer (or test) that destructures the config. Phase A's `@deprecated` + `@internal` produces lint warnings without breaking compilation.
+
+## Signal vs authority
+
+- **`validateRule1` is signal-only** — it returns a structured result. Decision authority lives in the enforcement-mode resolver + the adapter's init code.
+- **`checkAndWarn` is signal + side-effect** — it emits the warning and writes telemetry, but its decision to refuse is delegated to the caller (`createOpenAiCodexAdapter`).
+- **`createOpenAiCodexAdapter` is the authority** — it reads the enforcement mode and either throws (`hard`) or proceeds (`warn`/`disabled`).
+- **The drift gate is structural authority** — at lint time, refuses to let the source regress past Phase A guardrails.
+
+## Over-block / under-block analysis
+
+**Over-block:** A user who legitimately depends on API-key auth on Codex will see a warning at adapter init. They can suppress it with the escape hatch env var (which logs loudly itself). Without the hatch, behavior is unchanged for them in Phase A; no refusal happens. Mitigation: the warning is loud enough to be noticed but not so noisy as to break workflow.
+
+**Under-block:** None — the validator covers the two attack surfaces spec 12 explicitly names (env var + auth.json shape). The drift gate prevents quietly re-adding the env read.
+
+## Level-of-abstraction fit
+
+- `credentials.ts` lives at the adapter root, sibling to `config.ts` (per spec 12). Future per-credential helpers belong there too.
+- `check-codex-rule1-drift.js` lives in `scripts/` next to other lint helpers (`lint-no-direct-destructive.js`).
+- Telemetry writes to the existing `.instar/security.jsonl` channel (per `feedback_signal_vs_authority` memory: telemetry events at this layer are signal; the security channel reader is authority).
+
+## Interactions
+
+- **`buildCodexChildEnv` (existing Spec 12 Rule 1a env-scrub)** — orthogonal. That helper strips `OPENAI_API_KEY` from spawn child env regardless of validator state. Both layers cooperate: validator detects auth shape; scrub ensures process trees never see the key.
+- **`openaiKeyLeakageCanary` (existing)** — orthogonal. The canary asserts no spawn ever leaks the key; the validator asserts no adapter ever reads it.
+- **`AuthCredentialInjection.validate` (existing)** — distinct concern. That validates a `ProviderCredential` shape passed by the caller; the new validator inspects the ambient env/auth.json at adapter init. Both can fail-fast independently.
+
+## Rollback cost
+
+Pure code change. To roll back, revert the four files (config.ts, credentials.ts, index.ts, lint script wiring) and the test file. The escape hatch + sunset constant make Phase A migration recoverable for users; rollback at the codebase level recovers the developer state too. The new tests would surface what's missing post-revert.
+
+## Verification
+
+- `npx tsc --noEmit` — clean.
+- `npm run lint` — green (includes the new drift check passing).
+- `npx vitest run tests/unit/providers/adapters/openai-codex/credentialsRule1.test.ts` — 23/23 green.
+- Manual: setting `OPENAI_API_KEY=sk-test` in the shell and constructing the adapter emits the expected warning + telemetry line.

package/upgrades/side-effects/codex-telegram-relay-bootstrap.md

@@ -0,0 +1,68 @@
+# Side-effects review — Codex Telegram-relay bootstrap fix
+
+**Version / slug:** `codex-telegram-relay-bootstrap`
+**Date:** `2026-05-18`
+**Author:** Echo
+**Second-pass reviewer:** self-review — additive structural fix; framework-aware; covered by new tests + scenario-level test-as-self.
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md` (Rule 2 + Codex/local-model parity).
+
+## Summary
+
+Codex-routed Telegram topics on v1.0.0 received user messages, processed them in the Codex CLI session, but never called `telegram-reply.sh` — the user only saw PresenceProxy standby messages and assumed the agent had ignored them. Claude Code-routed topics didn't have this bug because a SessionStart shell hook (`.claude/hooks/instar/session-start.sh`) re-injects "MANDATORY: After EVERY response, relay…" at every session start. Codex CLI has no analogous hook system, so the relay convention has to live somewhere structural in the prompt context.
+
+Three changes, shipped together so the fix is durable across both turn-1 spawn and every subsequent injection within a long-running session:
+
+1. **`src/messaging/shared/telegramRelayPrompt.ts` (new).** Pure helper that emits the inline "Telegram Relay (MANDATORY)" block with the exact bash command, framework-aware. Imported by every bootstrap-construction call site.
+
+2. **`src/commands/server.ts` + `src/server/routes.ts`.** All three Telegram bootstrap paths (spawnSessionForTopic, /internal/telegram-forward main, /internal/telegram-forward Secret Drop) now append the relay block inline. Previously the relay instruction lived in a side ctx file that the agent was supposed to read — Codex apparently treats that as skippable background, not a structural directive.
+
+3. **`src/core/IdentityRenderer.ts`.** New `appendTelegramRelayBlock` option auto-appends a "## Telegram Relay (MANDATORY)" section to AGENTS.md/CLAUDE.md at render time. AGENTS.md is loaded into Codex's system prompt for the entire session lifetime, so this covers every subsequent turn — not just turn 1. Idempotent: existing shadows with the appendix are skipped; missing-appendix shadows get re-rendered when the caller asks.
+
+Plus the test-as-self framework upgrade Justin requested:
+
+4. **`run-v1-scenarios.py`.** New `is_sentinel_text` helper recognizes sentinel/proxy patterns (✓ Delivered, Session restarting, Session respawned, 🔭/✷︎ prefix + "N-minute update/check", "appears to be stuck", "Reply unstick", etc.). `wait-for-response` excludes them by default; scenarios that legitimately want sentinel-acceptance can opt in via `acceptSentinel: true`. Without this, every "did the agent reply?" assertion was satisfied by sentinel chatter — the exact failure mode the screenshot caught.
+
+5. **Two new scenarios.** `12-codex-telegram-roundtrip` flips topic 2525 to Codex and asserts a non-sentinel "PONG12" reply within 120s. `13-local-model-telegram-roundtrip` does the same for the Codex --oss + Ollama passthrough (degrades to cloud Codex if the operator hasn't configured `topicCodexLocalProvider`, still passes because the assertion is "agent replied at all").
+
+## Decision-point inventory
+
+- **Inline bootstrap relay block** — `change`. The previous ctx-file indirection was structurally too weak for Codex. Mirrors signal-vs-authority: the relay convention is authoritative, not optional context.
+- **AGENTS.md appendix** — `add`. New structural surface, gated on `appendTelegramRelayBlock: true` so non-Telegram installs aren't affected.
+- **Idempotent re-render when appendix missing** — `change`. ensureFrameworkIdentityFile's "shadow exists → no-op" was too coarse; we need to re-render when the appendix is missing but requested.
+- **Sentinel-exclusion in test driver** — `change`. The default-true behavior is "agent must really reply"; the opt-in for sentinel-friendly scenarios stays narrow.
+
+## Signal vs authority
+
+- The relay block is authoritative: presence in the prompt is enforced by the bootstrap path (server.ts/routes.ts) and by IdentityRenderer. Removal regresses obvious behavior.
+- Sentinels remain signal: they detect agent silence and emit standby messages, but they don't carry the agent's voice. The test driver's `is_sentinel_text` filter encodes this distinction structurally.
+
+## Over-block / under-block analysis
+
+**Over-block:** None. Existing Claude installs receive the same inline block; their SessionStart hook also fires — duplicate reminder is harmless (Claude already complies). Codex installs receive the block where they previously received nothing.
+
+**Under-block:** None. The block is appended to every Telegram-spawned session regardless of framework; the appendix renders into both AGENTS.md (Codex) and CLAUDE.md (Claude) when callers pass `appendTelegramRelayBlock: true`.
+
+## Level-of-abstraction fit
+
+- `buildTelegramRelayBlock` lives in `src/messaging/shared/` next to `isSystemOrProxyMessage` — peer location for shared message-classification helpers.
+- IdentityRenderer extension stays in IdentityRenderer; no new module.
+- Test driver changes stay in the existing runner; no new entry point.
+
+## Interactions
+
+- Coexists with the SessionStart shell hook (Claude Code path) — the bootstrap inline block is harmless redundancy when the hook fires.
+- Coexists with PresenceProxy: when the agent now replies for real, PresenceProxy's standby messages stop appearing because the agent's reply clears the watchdog. Verified end-to-end in scenario 12 (PONG12 reply lands, sentinel chatter stops).
+- The `telegram-reply.sh` template drift surfaced during scenario validation: deep-signal had an OLD relay script that posted directly to Telegram instead of through the local server. This is fixed by `TemplatesDriftVerifier` + PostUpdateMigrator's hook-overwrite path on the next `instar update`; the fix here is structurally independent.
+
+## Rollback cost
+
+- Revert is one commit. Restored behavior is "Codex sessions don't relay, sentinels fill the gap" — the bug, but no data loss.
+- No schema changes. AGENT.md (canonical source) is unchanged; only the rendered shadows gain the appendix.
+
+## Verification
+
+- `npx tsc --noEmit` clean.
+- `npm run lint` clean (Rule 1 drift gate green).
+- New unit tests: `tests/unit/telegramRelayPrompt.test.ts` (7 tests), `tests/unit/IdentityRenderer.test.ts` extended (+5 new tests for appendTelegramRelayBlock).
+- End-to-end on deep-signal (running v1.0.0 + this fix deployed): 14/14 scenarios PASS, including 12-codex-telegram-roundtrip (PONG12 codex-cli) and 13-local-model-telegram-roundtrip (PING13 gpt-5.3-codex).
+- Pre-fix scenario 12 deterministically FAILS with the correct diagnostic: "last sentinel message seen: '🔭 deep-signal is actively working…' — the agent itself never replied, only sentinels did". This is the regression-prevention shape Justin asked for.