instar 0.28.113 → 0.28.115

package/upgrades/side-effects/phase-5b5b-telegram-confirmation-transport.md

@@ -0,0 +1,68 @@
+# Side-effects review — Phase 5b.5.b TelegramConfirmationTransport
+
+**Version / slug:** `phase-5b5b-telegram-confirmation-transport`
+**Date:** `2026-05-16`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (push→pull bridge with per-topic waiter queue; full edge-case coverage in tests against a fake adapter)
+**Driving spec:** `specs/provider-portability/10-suggest-and-confirm-ux.md`
+
+## Summary of the change
+
+Phase 5b.3 shipped `TelegramConfirmer` against a stub `ConfirmationTransport`. This slice implements the real transport that bridges the existing MessagingAdapter (push-based via `onMessage`) to the `ConfirmationTransport` contract (pull-based via `awaitReply`).
+
+Design:
+- **`TelegramConfirmationTransport`** in `src/providers/uxConfirm/TelegramConfirmationTransport.ts`.
+- Takes a `MinimalMessagingAdapter` (slice of MessagingAdapter — send + onMessage only), a topic-extractor (`topicFromInbound`), and an outbound-shaper (`outboundForTopic`). Composable: same code drives Slack/iMessage/etc. when those land.
+- Per-topic waiter queue: `awaitReply(topicId, timeoutMs)` registers a waiter; inbound message → look up waiter → resolve. On timeout, resolve with null.
+- **Supersession**: a new `awaitReply` on a topic with a pending waiter resolves the prior waiter with null (the new confirmation has pre-empted it). Caller treats null as `default-no-reply` which is semantically correct.
+- **Drop-on-no-waiter**: inbound messages without a registered waiter are silently dropped. Prevents stale replies from satisfying future confirmations.
+- **Shutdown**: resolves every pending waiter with null so the event loop doesn't hold open.
+
+Files touched:
+- `src/providers/uxConfirm/TelegramConfirmationTransport.ts` — new, 175 LOC.
+- `tests/unit/providers/uxConfirm/TelegramConfirmationTransport.test.ts` — new, 9 cases against a fake adapter.
+
+## Decision-point inventory
+
+- **Topic matching** — `add`. The transport decides "does THIS inbound message satisfy THAT awaitReply?" by comparing topic ids. Per signal-vs-authority, this is fine — the consequence of a mismatch is "the wait continues until timeout," not a wrong-confirmation.
+- **Waiter supersession** — `add`. When two confirmations on the same topic overlap, the newer wins. This is the spec edge-case "Two Telegram messages arrive in quick succession" — implemented as a structural property of the queue rather than a downstream policy.
+- **Drop-on-no-waiter** — `add`. Inbound messages that don't match any active waiter get discarded silently. Prevents the "user replied before we asked" race from satisfying a later prompt with a stale message.
+
+## Signal vs authority
+
+The transport is a signal-routing layer. It doesn't decide anything itself — it routes inbound text to whichever waiter is registered for the topic. The `TelegramConfirmer` above it is the authority that interprets the reply text.
+
+## Over-block / under-block analysis
+
+**Over-block:** A user who replies during a confirmation but to a different topic gets ignored (correctly). Their reply doesn't satisfy the wrong prompt.
+
+**Under-block:** Drop-on-no-waiter means a user who replies BEFORE the prompt arrives (e.g., they were mid-typing) gets ignored. Their reply doesn't satisfy the LATER prompt. This is correct: a stale reply shouldn't fool the gate into thinking the user has consented.
+
+A user who replies *just barely* before the supersession edge case — i.e., reply 1 arrives nanoseconds after the prior waiter was resolved by the new awaitReply — will have their reply dropped (the new waiter hasn't registered yet). This is theoretical; in practice the new awaitReply registers synchronously after resolving the prior. Worst case: the next reply still works.
+
+## Level-of-abstraction fit
+
+- The transport sits in `src/providers/uxConfirm/` alongside the confirmer. Pulls only the narrow MinimalMessagingAdapter slice — doesn't need the full MessagingAdapter contract.
+- Provider-agnostic: name is "TelegramConfirmationTransport" because Phase 5b is Telegram-only per spec, but the same class trivially works for Slack/iMessage/etc. when those land — caller supplies a different topic-extractor and outbound-shaper.
+
+## Interactions
+
+- **`TelegramConfirmer` (Phase 5b.3)** — consumes a `ConfirmationTransport`. This class implements that interface. The confirmer's tests run against a stub; this transport adds the real implementation.
+- **Existing `MessagingAdapter` implementations** — unchanged. The transport calls `onMessage(handler)` which is already part of the contract.
+- **No existing source files modified** except the additive new ones.
+
+## External surfaces
+
+- New exports: `TelegramConfirmationTransport`, `TelegramConfirmationTransportOptions`, `MinimalMessagingAdapter`, `InboundMessage`.
+- No new endpoint, no new CLI command, no new config field.
+
+## Rollback cost
+
+Trivial. `git revert` removes two new files. The TelegramConfirmer still works against any other `ConfirmationTransport` implementation (e.g., the stubs in its own tests).
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/providers/uxConfirm/TelegramConfirmationTransport.test.ts` — 9/9 pass.
+- Coverage: send-delegation, inbound match-by-topic, ignore-different-topic, ignore-no-topic, timeout-returns-null, drop-when-no-waiter, supersession-same-topic (prior gets null), no-supersession-across-topics, shutdown-resolves-all.
+- No real-API verification needed in this slice — bridging logic is deterministic against a fake adapter. The live Telegram round-trip happens at composition-root wiring (Phase 5b.5.c) and again at the E2E test slice (Tier 4.C).

package/upgrades/side-effects/phase-5b5c-route-cli.md

@@ -0,0 +1,106 @@
+# Side-effects review — Phase 5b.5.c `instar route` CLI
+
+**Version / slug:** `phase-5b5c-route-cli`
+**Date:** `2026-05-16`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (additive CLI surface, no behavior change to existing endpoints)
+**Driving spec:** `specs/provider-portability/10-suggest-and-confirm-ux.md`
+
+## Summary of the change
+
+Adds `instar route <task...>` — a CLI subcommand that constructs the Phase 5b
+composition root (TaskClassifier + OverrideDetector + PreferenceStore +
+StaticCatalogProvider + CostStateTracker + TelegramConfirmer + FrameworkModelRouter)
+and runs a single classification against a task description.
+
+Pragmatic CLI-first approach: the full HTTP endpoint requires touching
+AgentServer's massive injected-dependencies constructor, which is risky to
+land overnight without Justin's review. The CLI command lets him test the
+end-to-end Phase 5b flow against his real IntelligenceProvider (Claude or
+Codex per `INSTAR_FRAMEWORK`) without the AgentServer wiring.
+
+Design choice: the CLI forces `telegramTopicId: null`, which short-circuits
+to the catalog-default branch (`source: auto-defaulted-no-topic`). This
+is deterministic and testable — no real Telegram round-trip needed. The
+TelegramConfirmer is wired with a no-op transport (the gate is never
+consulted on this code path; transport is there for type-soundness only).
+
+Files touched:
+- `src/commands/route.ts` — new, 140 LOC.
+- `src/cli.ts` — added `.command('route <task...>')` block, 13 LOC.
+
+## Decision-point inventory
+
+- **CLI vs HTTP** — `defer`. The HTTP endpoint requires wiring the router
+  into AgentServer's constructor, which has 20+ injected dependencies.
+  That wiring is tracked separately; the CLI subset is sufficient to
+  exercise the composition root and surface integration bugs.
+- **No-topic short-circuit** — `add`. Forces the deterministic catalog-
+  default branch in CLI context. Caller never sees an unfinished
+  confirmation. Per spec: "no Telegram topic → auto-default with note."
+- **Framework selection** — `add`. CLI accepts `--framework` flag plus
+  falls through to `frameworkFromEnv()` plus default `claude-code`. Honors
+  Tier 1.C's stated precedence.
+
+## Signal vs authority
+
+The CLI is a thin authority — it constructs the router and prints the
+result. The router itself is the authority for the routing decision;
+this CLI doesn't override or filter anything. Safe by construction.
+
+## Over-block / under-block analysis
+
+**Over-block:** None — the command is read-only with respect to runtime
+state (does write to `framework-model-preferences.db` if the router
+takes a cache-writing branch, but the CLI's no-topic path doesn't write).
+
+**Under-block:** A user could pass `--framework codex-cli` without having
+Codex installed; the `buildIntelligenceProvider` call would return null
+and the CLI exits with a clear error. Verified by the explicit null-check
+in route.ts.
+
+## Level-of-abstraction fit
+
+- Lives in `src/commands/route.ts` alongside other CLI entrypoints.
+- Imports the Phase 5b composition root by interface, not by concrete
+  type — same pattern as existing CLI subcommands (`gate`, `playbook`,
+  `memory`).
+- Does NOT touch AgentServer, HTTP routes, or Telegram wiring. That
+  scope is intentionally deferred.
+
+## Interactions
+
+- **`FrameworkModelRouter` (Phase 5b.4)** — consumed unchanged.
+- **`buildIntelligenceProvider` (Tier 1.C)** — consumed unchanged.
+- **`PreferenceStore`** — creates a sqlite file at `<stateDir>/framework-
+  model-preferences.db` if it doesn't exist. The path is stable across
+  CLI runs and any future HTTP wiring; both will share the cache.
+- **No existing source files modified** except `src/cli.ts` (additive
+  command registration).
+
+## External surfaces
+
+- New CLI command: `instar route <task...> [--user <id>] [--description <text>]
+  [--framework <name>] [--json] [-d <dir>]`.
+- No new endpoint, no new config field, no new environment variable.
+
+## Rollback cost
+
+Trivial. `git revert` removes the two files / hunks. No other code consumes
+the CLI command.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest run tests/unit/providers/uxConfirm/` — 124/124 pass (existing
+  router tests cover the no-topic branch the CLI invokes).
+- No new tests for `route.ts` itself: it's a thin composition wrapper
+  whose behavior is fully covered by `FrameworkModelRouter.test.ts`
+  ("auto-defaulted-no-topic" path) and `intelligenceProviderFactory.test.ts`
+  (framework selection). A test for `route.ts` would just be re-asserting
+  those wired together, with no new edge cases.
+- End-to-end smoke: invoking `node dist/cli.js route "refactor this function"`
+  on a Claude-installed machine should print `framework: claude-code`,
+  `model: opus-4.7` (the catalog default for code-refactor patterns).
+  Verified manually post-build; full live verification deferred to the
+  morning hand-back.

package/upgrades/side-effects/phase-5c-cost-aware-routing.md

@@ -0,0 +1,81 @@
+# Side-effects review — Phase 5c cost-aware routing infrastructure
+
+**Version / slug:** `phase-5c-cost-aware-routing`
+**Date:** `2026-05-15`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (pure-function policy + tracker with deterministic decision matrix; full unit-test coverage of every branch)
+**Driving spec:** `specs/provider-portability/11-cost-aware-routing.md` (locked + approved 2026-05-15) which implements §"Routing default" of `04-anthropic-path-constraints.md`
+
+## Summary of the change
+
+Phase 5c adds the deterministic routing math that sits below the Phase 5b UX. Two new classes live in `src/providers/costAwareRouting.ts`:
+
+1. **`CostAwareRoutingPolicy`** — implements the existing `RoutingPolicy` interface from `src/providers/routing.ts`. Given a candidate adapter list and a `readSdkCredit()` function, returns a `RoutingDecision` that picks SDK-credit-path when the credit pot is above the safety margin (default 10% of monthly total), subscription-floor otherwise. Six-row decision matrix (both/SDK-only/subscription-only × healthy/below-margin/unknown). Throws when neither Anthropic candidate is in scope so `ChainPolicy` defers to the next policy.
+
+2. **`CostStateTracker`** — emits structured `CostStateSnapshot` objects Phase 5b's TriggerGate uses to detect "material" cost shifts between cached preferences. Three material-shift categories: crossed safety margin (either direction), drifted ≥25% of total since prior snapshot, or known↔unknown state transition.
+
+23 unit tests cover every row of the decision matrix, the three material-shift categories, option validation, and the documented default constants.
+
+This phase is purely additive infrastructure. It is NOT wired into the runtime — `Registry.setRoutingPolicy()` is not called from any composition root in this commit. Wiring happens at server startup as part of Phase 5b's implementation (next phase).
+
+Files touched:
+- `src/providers/costAwareRouting.ts` — new, 199 LOC, contains both classes + constants + types.
+- `tests/unit/providers/costAwareRouting.test.ts` — new, 23 cases.
+- `specs/provider-portability/11-cost-aware-routing.md` — new spec, locked + approved 2026-05-15.
+- `specs/provider-portability/11-cost-aware-routing.eli16.md` — mandatory ELI16 companion.
+
+## Decision-point inventory
+
+This change ADDS decision-point surface. It is itself a decision point — picks which adapter handles an Anthropic-bound request — and its implementation interacts with the existing `RoutingPolicy` / `ChainPolicy` decision chain.
+
+- **`CostAwareRoutingPolicy.decide(candidates, request)`** — `add`. The new authority for SDK-credit-vs-subscription routing of Anthropic-bound traffic.
+- **`CostStateTracker.snapshot()`** — `add`. Pure-observability signal source. No blocking authority. Phase 5b reads the snapshot but the tracker doesn't gate anything itself.
+- **`CostStateTracker.isMaterialShift(prior, current)`** — `add`. Pure function — returns a reason string or null. Phase 5b's TriggerGate is the authority that decides what to do with the reason.
+
+No existing decision points are modified. The existing `RoutingPolicy` / `ChainPolicy` / `FirstAvailablePolicy` interfaces in `src/providers/routing.ts` are unchanged.
+
+## Signal vs authority
+
+- `CostAwareRoutingPolicy` is an authority — it returns a `chosen` adapter id that the registry uses. Authority scope is narrow: only Anthropic-stack candidates. Outside that scope it throws so `ChainPolicy` defers.
+- `CostStateTracker` is a signal producer only. It captures snapshots and computes deltas. It never blocks. The downstream authority (Phase 5b's TriggerGate) interprets the signal.
+- Both classes are pure-input-pure-output where possible. The `readSdkCredit` function is the only external dependency; both classes tolerate its absence/failure without panicking.
+
+## Over-block / under-block analysis
+
+**Over-block:**
+- A flaky `readSdkCredit` (transient null/throw) routes all work to subscription floor until it recovers. Subscription floor is always-correct per Rule 1, so this is graceful degradation, not over-block.
+- A misconfigured `safetyMarginFraction = 1.0` (rejected at construction by option validation) would route everything to subscription regardless of credit. Construction-time validation prevents this.
+
+**Under-block:**
+- A reader that returns stale data (cached snapshot from minutes ago) could pick SDK adapter when the pot has actually drained since the cache. Bounded by however quickly the caller refreshes the reader. Recommended: call `readSdkCredit` per-decision, not per-app-lifetime.
+- The `materialDriftFraction = 0.25` threshold means Phase 5b won't re-ask for drift < 25%. A user who'd want awareness at, say, 10% drift would need to override the option. Defaults are intentionally permissive to avoid prompt spam.
+
+## Level-of-abstraction fit
+
+- The policy lives in `src/providers/costAwareRouting.ts` (parallel to `src/providers/routing.ts` where the interface lives). It depends only on `RoutingPolicy`, `ProviderAdapter`, `AgentSdkCreditSnapshot`. No knowledge of specific adapter internals.
+- The tracker shape (`CostStateSnapshot`) is the contract Phase 5b will consume. Defining it here keeps Phase 5b free of Anthropic-specific details — future tracker extensions (subscription-window state, per-provider budgets) extend the snapshot shape without rewriting Phase 5b.
+
+## Interactions
+
+- **Existing `RoutingPolicy` / `ChainPolicy`** — composes naturally. The recommended chain (`PinHonoring → CostAware → FirstAvailable`) is documented in the spec but not constructed in this commit.
+- **`UsageMeterProvider`** — typical `readSdkCredit` implementation wraps a `UsageMeterProvider.read()` call and extracts `agentSdkCredit`. This commit does not include the wrapper because the application-layer wiring happens during Phase 5b implementation.
+- **No changes to existing source files.** Pure addition. Zero regression surface.
+
+## External surfaces
+
+- `CostAwareRoutingPolicy` — new exported class.
+- `CostStateTracker` — new exported class.
+- `CostAwareRoutingOptions`, `CostStateTrackerOptions`, `CostStateSnapshot` — new exported types.
+- `DEFAULT_SAFETY_MARGIN_FRACTION` — new exported const (0.10).
+- No new endpoint, no new CLI command, no new config field. Wiring is composition-root concern.
+
+## Rollback cost
+
+Trivial. `git revert` removes one source file + one test file + two spec files + this artifact. No persistent state, no runtime callsites. Zero blast radius.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/providers/costAwareRouting.test.ts` — 23/23 pass.
+- Branch coverage: every row of the decision matrix has at least one passing case; every material-shift category has at least one passing case; option-validation rejects out-of-range fractions.
+- No real-API verification needed — `readSdkCredit` is a pure function dependency stubbed in tests. Production wiring (where `readSdkCredit` becomes a `UsageMeterProvider` call) gets real-API verification as part of Phase 5b implementation.

package/upgrades/side-effects/portability-generic-tier-routing.md

@@ -0,0 +1,85 @@
+# Side-effects review — Generic tier routing + framework-aware /sessions/spawn whitelist + Codex config-readable default model
+
+**Version / slug:** `portability-generic-tier-routing`
+**Date:** `2026-05-18`
+**Author:** Echo
+**Second-pass reviewer:** self-review — 197 unit tests across 8 files green; typecheck clean; refactor is pure call-site rewiring of an already-converged tier abstraction
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md`
+
+## Summary of the change
+
+Tracks D + E of the v1.0.0 provider-portability autonomous cycle. Three related fixes:
+
+1. **Generic tier mapping helper** — `resolveModelForFramework(framework, modelOrTier)` in `src/core/frameworkSessionLaunch.ts`. Maps the cross-framework tiers (`fast`/`balanced`/`capable`) to each framework's preferred concrete model. Legacy Claude tier names (`haiku`/`sonnet`/`opus`) also resolve correctly for both frameworks so unported callsites don't crash for Codex agents. Raw model ids pass through verbatim.
+
+2. **buildInteractiveLaunch + buildHeadlessLaunch route through the helper** — the codex builder's hardcoded `gpt-5.3-codex` (line 88) is now a `resolveModelForFramework('codex-cli', options.defaultModel) ?? 'gpt-5.3-codex'` lookup so config can override. The claude builder applies the same tier-expansion so generic tiers like `'fast'` correctly become `'haiku'` on the Claude CLI's `--model` flag.
+
+3. **UpgradeNotifyManager MODEL_CHAIN uses generic tiers** — `['fast', 'balanced']` instead of `['haiku', 'sonnet']`. UpgradeNotifyResult.model becomes `GenericModelTier`. SessionSpawner callback widens to accept `GenericModelTier | ModelTier | string`. The framework-specific resolution happens inside SessionManager.spawnSession via the headless builder.
+
+4. **SessionManager.spawnSession.options.model widened** to `ModelTier | string` so generic tiers + raw model ids flow through cleanly. Session.model type widened to `ModelTier | string` for the same reason. No semantic change for Claude installs (existing Claude tier names continue to work).
+
+5. **/sessions/spawn route accepts a `framework` field + framework-aware model whitelist**. Generic tiers are universally accepted; framework-specific tier names are accepted only when they match the requested framework slot. Error messages name the framework so misconfigurations are obvious.
+
+6. **frameworkSessionLaunch codex hardcoded model becomes config-readable** via `SessionManagerConfig.frameworkDefaultModels?.['codex-cli']`. `spawnInteractiveSession` reads from this map and passes it as `defaultModel` into `buildInteractiveLaunch`.
+
+7. **StallTriageNurse model tier normalization is framework-aware**. Previously `DEFAULT_CONFIG.model` was always resolved through Claude-only `resolveModelId`, which would produce `'claude-sonnet-4-6'` even when running under a Codex agent. Now `framework` from the merged config selects the tier resolver: Codex agents get `'gpt-5.3-codex'` for `'balanced'`; Claude agents still get `'claude-sonnet-4-6'`. Raw model ids pass through both paths.
+
+Files touched:
+- `src/core/frameworkSessionLaunch.ts` — adds `GenericModelTier` type, `resolveModelForFramework`, `InteractiveLaunchOptions.defaultModel`. Both builders route through the helper.
+- `src/core/types.ts` — `Session.model` widened to `ModelTier | string`; `SessionManagerConfig.frameworkDefaultModels` added.
+- `src/core/SessionManager.ts` — spawnSession.options.model widened; spawnInteractiveSession reads frameworkDefaultModels.
+- `src/core/UpgradeNotifyManager.ts` — MODEL_CHAIN → generic tiers; UpgradeNotifyResult.model + SessionSpawner.model widened.
+- `src/monitoring/StallTriageNurse.ts` — framework-aware DEFAULT_CONFIG.model + per-framework resolver in constructor.
+- `src/server/routes.ts` — /sessions/spawn accepts `framework` + framework-aware model whitelist.
+- 4 test files updated for tier-name change; 2 new test suites added.
+
+## Decision-point inventory
+
+- **GenericModelTier vocabulary** — `add`. Three-tier shape mirrors `IntelligenceOptions.model` so the same vocabulary works in evaluate() and spawn paths.
+- **/sessions/spawn whitelist** — `extend`. Old: `['opus','sonnet','haiku']` only. New: framework-aware union of generic tiers + framework-specific names. Strict positive-list — unknown model strings still 400.
+- **StallTriageNurse framework-conditional model resolution** — `change`. Old behavior assumed Claude. New behavior reads `mergedFramework` and picks the right resolver. Back-compat verified: Claude path still produces `'claude-sonnet-4-6'` for the default `'sonnet'` tier.
+- **frameworkDefaultModels config field** — `add`. Optional. Missing keys fall back to each builder's existing default.
+- **STALL_TRIAGE_MODEL env var semantics** — `change`. Previously interpreted strictly as a Claude alias. Now interpreted as a tier OR raw id, resolved per-framework. For existing Claude-only deployments this is a no-op (`'sonnet'` → `'claude-sonnet-4-6'` unchanged).
+
+## Signal vs authority
+
+- `resolveModelForFramework` is a pure function (signal). It maps strings to strings. No blocking authority.
+- The /sessions/spawn whitelist is **authority** — it returns 400 and prevents the spawn when the model isn't recognized for the framework. This was already authoritative for Claude; now it's framework-aware authority.
+- StallTriageNurse stores a resolved model id but doesn't pre-gate any LLM call on it (the actual evaluate() call uses `model: 'balanced'` literal). The resolution is currently observational — useful for logs/tooling that greps the config field, no behavioral implication.
+
+## Over-block / under-block analysis
+
+**Over-block:** New /sessions/spawn whitelist could 400 calls that previously passed. Mitigation: generic tiers `fast`/`balanced`/`capable` are universally accepted regardless of framework, so any caller using generic tiers continues to work. Framework-specific names still work when they match the framework (default `claude-code` → accepts old `opus`/`sonnet`/`haiku`).
+
+**Under-block:** None — the whitelist is strictly positive, and the framework field defaults to `claude-code` so omitting it preserves the prior strictness.
+
+## Level-of-abstraction fit
+
+- `resolveModelForFramework` lives in `frameworkSessionLaunch.ts` next to the launch builders that consume it. Single home for "tier semantics for X framework."
+- Tier vocabulary (`fast`/`balanced`/`capable`) matches the existing `IntelligenceOptions.model` field so callers don't have to learn a second vocabulary.
+- Default-model config lives on `SessionManagerConfig.frameworkDefaultModels`, mirroring the existing `frameworkBinaryPaths` shape.
+
+## Interactions
+
+- **buildInteractiveLaunch / buildHeadlessLaunch** — both now use the helper. Tier names pass through identically; raw model ids pass through identically.
+- **UpgradeNotifyManager spawnSession callback** — caller (server.ts wiring, not in this PR) only needs to widen the callback signature; passing generic tier strings to SessionManager.spawnSession works.
+- **CostAwareRoutingPolicy / FrameworkModelRouter** — orthogonal. They decide which model TIER to use; the helper decides which concrete name that tier maps to per framework. Stacks cleanly.
+- **Anthropic path constraints (Rule 2)** — preserved. The Anthropic path resolver still runs for `claude-code` agents to expand tier → canonical Anthropic id.
+
+## Rollback cost
+
+Pure code change. No persistent state migration; the `frameworkDefaultModels` config field is optional and ignored when missing. Reverting the commits restores the legacy hardcoded `gpt-5.3-codex` + Claude-only tier vocabulary; the new tests would surface the missing surfaces immediately. Test suite stays green either way (the new tests assert new behavior; the unchanged tests assert preserved behavior).
+
+## Verification
+
+- `npx tsc --noEmit` — clean.
+- 197 unit tests across 8 files green:
+  - tests/unit/frameworkSessionLaunch.test.ts (30)
+  - tests/unit/pipeSessionSpawnerFrameworkPortability.test.ts (11)
+  - tests/unit/StallTriageNurse.test.ts (66) — incl. 5 new tier-resolution cases
+  - tests/unit/UpgradeNotifyManager.test.ts (17) — generic-tier expectations
+  - tests/unit/upgrade-notify-manager.test.ts (17) — generic-tier expectations
+  - tests/unit/route-validation-edge.test.ts (26)
+  - tests/unit/session-manager-behavioral.test.ts (22)
+  - tests/unit/listener-daemon.test.ts (18)
+- v1.0.0 scenarios — to run after commit, before push.

package/upgrades/side-effects/portability-headless-launch-helper.md

@@ -0,0 +1,76 @@
+# Side-effects review — Portability cycle: buildHeadlessLaunch + spawnSession + PipeSessionSpawner
+
+**Version / slug:** `portability-headless-launch-helper`
+**Date:** `2026-05-18`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** self-review (mirrors the buildInteractiveLaunch shape exactly; 50 unit tests green; pure code change, no schema / config migration)
+**Driving spec:** `docs/specs/SPEC-PROVIDER-PORTABILITY.md` (approved)
+
+## Summary of the change
+
+Continuation of the provider-portability cycle. Until this PR, three production paths still hardcoded the Claude CLI flag set inline:
+
+1. `SessionManager.spawnSession` (headless prompt path) built `claude --dangerously-skip-permissions [--model X] -p <prompt>` directly.
+2. `PipeSessionSpawner.classifyIntent` shell-executed `claude -p --model haiku` to classify threadline messages.
+3. `PipeSessionSpawner.summarizeThreadHistory` shell-executed `claude -p --model haiku` to compress thread history.
+4. `PipeSessionSpawner.spawn` shell-executed `cat <promptfile> | claude -p --model <m> --allowedTools <list>` to spawn a pipe-mode session.
+
+Codex installs couldn't use any of these paths even after the `IntelligenceProvider` factory shipped, because the factory only covered the abstract evaluate path — these four spawn callsites bypassed it entirely.
+
+This cycle:
+
+1. **Adds `buildHeadlessLaunch(framework, options)`** to `src/core/frameworkSessionLaunch.ts` — companion to the existing `buildInteractiveLaunch`. Same shape, same exhaustiveness check, same envOverrides contract. Claude builder: `[bin, '--dangerously-skip-permissions', '--model'?, '-p', prompt]`. Codex builder: `[bin, 'exec', '--json', '--skip-git-repo-check', '-s', sandbox, '-m', model, prompt]`.
+2. **Refactors `SessionManager.spawnSession`** to route through `buildHeadlessLaunch`. Adds a per-call `framework?: IntelligenceFramework` override on the options surface; falls back to `INSTAR_FRAMEWORK` env. Reads the binary path from `config.frameworkBinaryPaths[framework]`, with `claudePath` as legacy fallback. Provider-specific env (`CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`) is gated on `framework === 'claude-code'` and never leaks into Codex tmux sessions.
+3. **Refactors `PipeSessionSpawner.classifyIntent` and `.summarizeThreadHistory`** to accept an `IntelligenceProvider` in their options. When given, they route through `.evaluate()` (which works for both Claude and Codex). When omitted, both fail closed — classifier returns `'interactive'`, summarizer returns the unavailable placeholder. This is intentional: the legacy bare-`claude` shell-exec assumed `claude` was on PATH, which silently broke Codex installs. Better to fail closed than to leak framework-specific behavior into shared code.
+4. **Refactors `PipeSessionSpawner.spawn`** to use `buildHeadlessLaunch`. The pre-existing secure-perm prompt file is preserved; the spawned shell command substitutes `$(< "$promptfile")` for the helper's prompt-positional placeholder so the prompt stays off the command line (no leak via `ps`). Env scrub block clears both `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` (Spec 12 Rule 1a).
+5. **Wires server.ts** to build the `PipeSessionSpawner` with `framework` + `binaryPath` from the resolved-framework + `frameworkBinaryPaths` map. Codex agents default to `gpt-5.3-codex` for pipe-mode; Claude agents default to `sonnet`.
+
+Files touched:
+- `src/core/frameworkSessionLaunch.ts` — +119 LOC (HeadlessLaunchOptions/Spec types, claude+codex headless builders, `buildHeadlessLaunch` dispatch).
+- `src/core/SessionManager.ts` — refactored spawnSession to use the helper; added `framework?` to options; replaced inline `claudeArgs` with `headlessSpec.argv`; gated anthropic-env on framework.
+- `src/threadline/PipeSessionSpawner.ts` — added `framework`+`binaryPath` to PipeSessionConfig; rewrote `classifyIntent` / `summarizeThreadHistory` to use injected IntelligenceProvider; rewrote `spawn` to use `buildHeadlessLaunch` + `$(< file)` substitution.
+- `src/commands/server.ts` — wires PipeSessionSpawner with framework + binaryPath; passes sharedIntelligence to `classifyIntent`.
+- `tests/unit/frameworkSessionLaunch.test.ts` — +11 new tests for buildHeadlessLaunch (21 total green).
+- `tests/unit/pipeSessionSpawnerFrameworkPortability.test.ts` — new, 11 tests covering classifier/summarizer fail-closed behavior + framework-aware spawn construction.
+
+## Decision-point inventory
+
+- **Headless launch builder dispatch** — `add`. New surface; no existing behavior touched. Exhaustiveness check forces a compile error when adding a new framework.
+- **spawnSession framework selection** — `add`. Per-call wins; env fallback. `configFramework` parameter is left as `undefined` for now because `SessionManagerConfig` has no top-level framework field — agent-level framework default propagates via `INSTAR_FRAMEWORK` env set at server boot.
+- **PipeSessionSpawner classifier fail-closed** — `change`. Old behavior: silently fell through to `'interactive'` on shell-exec failure. New behavior: same `'interactive'` fall-through, but the trigger is `intelligence==null` rather than the shell call failing. No outward semantic change for Claude installs (the shell call always succeeded when claude was on PATH); Codex installs that previously got the silent fallback now get the same fallback through a documented code path.
+- **Spec 12 Rule 1a coverage** — `extend`. PipeSessionSpawner's env-scrub block now clears `OPENAI_API_KEY` alongside the existing `ANTHROPIC_API_KEY`. Previously only Claude was scrubbed.
+
+## Signal vs authority
+
+- `buildHeadlessLaunch` and `buildInteractiveLaunch` are **pure functions** (signal producers — return argv + env). They have no blocking authority.
+- The authority that decides whether a session spawns at all is `SessionManager.spawnSession` (which checks `maxSessions` and tmux state) — this didn't change.
+- The classifier's `'interactive'` fail-closed is **signal** ("I don't know whether this is a TASK"). The pipe-mode gate above it is the authority that decides whether to spawn a pipe session. This separation was already correct; the refactor preserves it.
+
+## Over-block / under-block analysis
+
+**Over-block (new failure mode introduced?):** The classifier now requires an `IntelligenceProvider` to ever return `'pipe'`. In degraded mode (no provider available), all messages go to interactive. This is a deliberate fail-closed: pre-portability, classifier-on-codex would have crashed because `claude` wasn't installed; the silent shell-exec error caught the crash but the result was still `'interactive'`. So the post-refactor behavior matches the pre-refactor effective behavior — no new over-block.
+
+**Under-block (anything previously gated now slipping through?):** No. The set of paths that gate on the classifier is the same. Spec 12 Rule 1a actually **gets stronger** here — OpenAI key scrubbing was missing from the pipe spawn previously.
+
+## Level-of-abstraction fit
+
+- `buildHeadlessLaunch` lives next to `buildInteractiveLaunch` in the same file. Same shape, same docstring style, same exhaustiveness pattern. Future frameworks add one builder + one BUILDERS entry per side.
+- `SessionManager.spawnSession` reads from `frameworkBinaryPaths` — the field that was designed for this exact lookup. No new config field needed.
+- `PipeSessionSpawner` takes `framework` + `binaryPath` as constructor fields, matching how `SessionManagerConfig` exposes them. The composition root (server.ts) is the single owner that ties detected paths to PipeSessionSpawner config.
+
+## Interactions
+
+- **buildInteractiveLaunch** — unchanged. Both builders coexist in the same file.
+- **CostAwareRoutingPolicy / FrameworkModelRouter** — orthogonal. Routing decides which model tier; helpers decide which CLI gets the prompt. Both stack.
+- **SessionManager.spawnInteractiveSession** — unchanged. This refactor only touches the headless (`-p` prompt) path.
+- **Spec 12 env-allowlist helpers** — defensive overlap is fine. PipeSessionSpawner now scrubs OPENAI_API_KEY before the framework's own env-allowlist runs.
+
+## Rollback cost
+
+Pure code change. No schema, no config migration, no on-disk state changes. Revert is a single `git revert <sha>` and the legacy `claude -p` inline path comes back. The new tests would fail post-revert and surface the missing helper immediately.
+
+## Verification
+
+- `npx tsc --noEmit` — clean.
+- `npx vitest run tests/unit/frameworkSessionLaunch.test.ts tests/unit/pipeSessionSpawnerFrameworkPortability.test.ts tests/unit/listener-daemon.test.ts tests/unit/session-manager-behavioral.test.ts tests/unit/session-telegram-inject.test.ts` — 74/74 green.
+- All v1.0.0 scenario tests (12 scenarios) — green in the parent autonomous loop.

package/upgrades/side-effects/post-merge-lint-allowlist.md

@@ -0,0 +1,44 @@
+# Side-effects review — Post-merge lint allowlist + release-guide cleanup
+
+**Version / slug:** `post-merge-lint-allowlist`
+**Date:** `2026-05-18`
+**Author:** Echo
+**Second-pass reviewer:** self-review — pure additive (allowlist expansion) + content fill (upgrade guide).
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md` (Rule 2 — AnthropicIntelligenceProvider deletion).
+
+## Summary
+
+Three post-merge fixups needed before the v1.0.0 push can pass the pre-push gate:
+
+1. **`scripts/lint-no-direct-llm-http.js` ALLOWLIST update.** Drops the deleted `src/core/AnthropicIntelligenceProvider.ts` entry; adds the seven `src/providers/adapters/anthropic-headless/*` files that are the LEGITIMATE Anthropic chokepoint in v1.0.0 (same role Phase 1 of the burn-detection spec envisioned for `AnthropicIntelligenceProvider`). Without this fix, the lint rule false-positives on every adapter API call.
+
+2. **Remove `src/core/badNewCode.ts` and `src/core/exemptCode.ts`.** These were stray test fixtures created by a misconfigured `check-rule3-coverage.test.ts` run on this worktree. The test uses `mkdtempSync` for its real fixtures; these files in `src/core/` shouldn't exist on disk. They tripped the lint rule (intentional violation inside the fixture file).
+
+3. **Fill in `upgrades/1.0.0.md` template placeholders.** "What to Tell Your User" gets four conversational bullets (per-topic framework swap, local model, upgrade safety, optional API-key warning). "Summary of New Capabilities" gets a five-row table. Removed HTML-comment scaffolding whose example text (`silentReject`, `maxRetries`) was tripping the camelCase config-key validator that runs at pre-push.
+
+## Decision-point inventory
+
+- **ALLOWLIST scope** — `extend`. The new entries are the anthropic-headless adapter's API touchpoints (authCredentialInjection, usageMeterProvider, oneShotCompletion, agenticSessionHeadless, errors, smoketest, fileSystemAccess). All are inside `src/providers/adapters/anthropic-headless/` and constitute the migrated Anthropic chokepoint.
+- **AnthropicIntelligenceProvider removal from ALLOWLIST** — `change`. The file is deleted; allowlisting a non-existent file is dead config.
+- **Stray fixture deletion** — `change`. These shouldn't have been on disk in the first place; the tests are unaffected.
+- **Upgrade guide content** — `add`. Fills in template placeholders; conforms to the user-facing-language rules baked into the validator.
+
+## Signal vs authority
+
+The lint rule is structural authority (blocks the build). The release-guide validator is structural authority (blocks publish). Both are pre-push gates with clear escalation. No semantic change to either.
+
+## Over-block / under-block analysis
+
+**Over-block:** None new. Removing `AnthropicIntelligenceProvider.ts` from the allowlist doesn't change behavior — the file doesn't exist. Adding anthropic-headless entries restores the intent of the original ALLOWLIST after the v1.0.0 chokepoint migration.
+
+**Under-block:** None. The anthropic-headless adapter IS the chokepoint per Phase 3a; allowing its API calls is exactly what the lint rule intends to permit.
+
+## Rollback cost
+
+Pure config change. Revert the script edit + delete the fixture-file deletion + revert the upgrade-guide content. Nothing depends on these for runtime behavior.
+
+## Verification
+
+- `node scripts/pre-push-gate.js` — warnings only, no errors.
+- `node scripts/check-codex-rule1-drift.js` — clean.
+- Manual: lint rule walks `src/` and produces no violations after the allowlist update.

package/upgrades/side-effects/post-update-migrator-bracket-fix.md

@@ -0,0 +1,36 @@
+# Side-effects review — PostUpdateMigrator bracket close fix
+
+**Version / slug:** `post-update-migrator-bracket-fix`
+**Date:** `2026-05-18`
+**Author:** Echo
+**Second-pass reviewer:** self-review — single-syntax-fix; no behavior change.
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md` (Rule 2 — provider-portability v1.0.0 migration recording).
+
+## Summary
+
+The `migrateProviderPortability` method shipped with an unclosed try/catch + missing method-close `}` between the `result.errors.push(...)` line and the next `// ── Fleet watchdog` comment. Local typecheck happened to clear during merge-resolution because of a stale dist/, but the source file's CI Type Check (`tsc --noEmit` from clean) failed at `src/core/PostUpdateMigrator.ts#238` with `TS1128: Declaration or statement expected.` and cascaded into every unit-test shard via ts-jest compilation.
+
+Fix: add the missing `}` (close catch) + `}` (close method) before the fleet-watchdog comment block. No behavior change.
+
+## Decision-point inventory
+
+- **Bracket close** — `change`. Pure syntax repair; restores the v1.0.0 migration's intended structure.
+
+## Signal vs authority
+
+CI Type Check is structural authority. Fix unblocks the gate; no new gates introduced.
+
+## Over-block / under-block analysis
+
+**Over-block:** None. The previous broken syntax aborted compile; nothing else was affected by it semantically.
+**Under-block:** None. The migration's intended guard (try/catch on config write) is now actually a try/catch.
+
+## Rollback cost
+
+Zero — reverting the two braces would re-introduce the syntax error.
+
+## Verification
+
+- `npx tsc --noEmit` — exit 0 locally.
+- CI Type Check re-runs on push.
+- Unit-test shards expected to pass once tsc compiles.

package/upgrades/side-effects/sentinel-monitoring-cross-port.md

@@ -0,0 +1,76 @@
+# Side-effects review — Sentinel + monitoring cross-port
+
+**Version / slug:** `sentinel-monitoring-cross-port`
+**Date:** `2026-05-18`
+**Author:** Echo
+**Second-pass reviewer:** self-review — 64 tests across InstructionsVerifier + PromptGate green; typecheck clean.
+**Driving spec:** `specs/provider-portability/00-functional-map.md` (D: Session health / stall / recovery; F: Interactive prompt detection).
+
+## Summary of the change
+
+Closes three of the four sentinel-cross-port residuals identified in the prior autonomous-cycle final report. The fourth (setup wizard) is explicitly documented as out-of-scope — Claude Code's skill system is Claude-specific and porting requires its own design pass.
+
+1. **InstructionsVerifier — framework-aware default expected pattern**
+   - Adds `framework?: 'claude-code' | 'codex-cli'` to `InstructionsVerifierConfig`.
+   - When framework is set, the default `expectedPatterns` resolves per-framework: `['CLAUDE.md']` for Claude Code, `['AGENTS.md']` for Codex.
+   - When framework is unset (migration-safe default), the verifier accepts EITHER `CLAUDE.md` OR `AGENTS.md` — passes if any one of them loads. This prevents false alarms during framework swaps where both files may transiently coexist.
+   - Explicit `expectedPatterns` still overrides everything (back-compat).
+
+2. **PromptGate — Codex CLI UI prompt detection**
+   - Confirmation pattern extended to detect both Claude's `"Esc to cancel · Tab to amend"` AND Codex's `"Ctrl+C to cancel"` / `"Press Ctrl-C to cancel"` variants.
+   - LLM gate prompt rewritten to mention Codex's UI tokens (`Ctrl+C to interrupt`, `> ` prompt, `Update Plan`, `Step N`, `Apply patch?`, `Run command?`) so the Haiku-class classifier doesn't false-positive Codex's status bar as a blocking prompt.
+   - First sentence widened from "Claude Code session" to "AI agent session (Claude Code OR OpenAI Codex CLI)".
+
+3. **Lifeline doctor session — framework-aware refusal for Codex**
+   - `spawnDoctorSession` now checks `INSTAR_FRAMEWORK`. For `codex-cli` it throws a typed error with explicit fallback messaging. The existing catch in `recoverWithSupervisor` already forwards the error to the user-facing topic, so Codex users see a clear "diagnostic spawn not supported, falling back to circuit-breaker reset" message instead of a silent crash loop.
+   - The doctor session uses Claude-specific flags (`--message -` stdin prompt, `--allowedTools` tool restriction) that have no direct Codex equivalent. Rather than building a half-port, v1.0.0 makes the Claude-only scope explicit and tracks the Codex doctor as Phase 6+ work.
+
+4. **Setup wizard — documented as Claude-only by design (no code change)**
+   - The wizard spawns Claude Code with `/setup-wizard` and `/secret-setup` skills. Those skills are part of Claude Code's skill system, not Instar's. Building Codex equivalents requires defining a new skill system in the Codex CLI, which is upstream territory. Documented in the v1.0.0 release notes as a residual.
+
+Files touched:
+- `src/monitoring/InstructionsVerifier.ts` — adds `framework` field, per-framework default resolution, cross-framework fallback.
+- `src/monitoring/PromptGate.ts` — extends confirmation regex + rewrites LLM gate prompt.
+- `src/lifeline/TelegramLifeline.ts` — adds framework guard to `spawnDoctorSession`.
+- `tests/unit/instructions-verifier.test.ts` — 7 new framework-aware cases (29 total green).
+- `tests/unit/PromptGate.test.ts` — 2 new Codex confirmation cases (35 total green).
+
+## Decision-point inventory
+
+- **InstructionsVerifier cross-framework fallback** — `add`. When the verifier doesn't know which framework is active (e.g., during a swap), accept either identity file. Prevents false-alarm churn.
+- **PromptGate Codex pattern variants** — `add`. `Ctrl+C to cancel` and `Press Ctrl-C to cancel` both captured.
+- **Lifeline doctor refusal for Codex** — `add`. Typed error reaches the catch, user sees a clear message instead of a confusing fallback.
+- **Setup wizard left Claude-only** — `deliberate non-action`. Cross-porting requires upstream Codex CLI changes (skill system), not Instar code changes.
+
+## Signal vs authority
+
+- All three components stay at their existing level. Verifier emits a signal; PromptGate emits detected-prompt events for downstream consumers; Lifeline doctor is authoritative for its own spawn decision (it now refuses for Codex instead of silently failing).
+
+## Over-block / under-block analysis
+
+**Over-block:** None. InstructionsVerifier's cross-framework fallback is strictly more permissive than the old default (anyone-of vs all-of). PromptGate's added Codex pattern can't fire on Claude output (Claude doesn't print `Ctrl+C to cancel`).
+
+**Under-block:** None new. The Codex doctor refusal is honest — recovery still proceeds via circuit-breaker reset, just without a diagnostic session.
+
+## Level-of-abstraction fit
+
+- All three changes are localized to their owning module. No cross-module refactor.
+- `framework` field on InstructionsVerifierConfig matches the convention used elsewhere (StallTriageNurseConfig already has the same field).
+- PromptGate's pattern union is the existing extension point — adding a new framework's UI strings is a single-line regex addition.
+
+## Interactions
+
+- **`spawnInteractiveSession` framework dispatch** — orthogonal. The spawn paths are framework-aware; the verifier observes what they loaded.
+- **StallTriageNurse framework field** — same pattern. Both now share the `framework: 'claude-code' | 'codex-cli'` convention.
+- **Doctor session caller (`recoverWithSupervisor`)** — preserved behavior. The catch already forwards the error message to the user-facing topic.
+
+## Rollback cost
+
+Pure code change. Revert any single file independently. No persistent state migrations, no schema changes.
+
+## Verification
+
+- `npx tsc --noEmit` — clean.
+- `npx vitest run tests/unit/instructions-verifier.test.ts` — 29/29 green.
+- `npx vitest run tests/unit/PromptGate.test.ts` — 35/35 green.
+- Manual: Codex framework env var triggers the doctor refusal path with the expected error message.