instar 0.28.113 → 0.28.114

package/upgrades/side-effects/tier-2e-subsystem-shared-intelligence.md

@@ -0,0 +1,115 @@
+# Side-effects review — Tier 2.E Subsystem framework-aware intelligence
+
+**Version / slug:** `tier-2e-subsystem-shared-intelligence`
+**Date:** `2026-05-16`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (single-flag substitution: every subsystem now consumes the already-framework-aware `sharedIntelligence` instead of constructing its own ClaudeCli provider)
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md`
+
+## Summary of the change
+
+Server-boot smoke test with `INSTAR_FRAMEWORK=codex-cli` confirmed
+`Intelligence: Codex CLI` for the primary `sharedIntelligence`, but
+some downstream subsystems were independently constructing
+`ClaudeCliIntelligenceProvider`, which silently routed their LLM calls
+through Claude even though the agent was supposed to be Codex-only.
+
+Affected subsystems:
+1. **RelationshipManager** — `config.relationships.intelligence` was
+   built from `new ClaudeCliIntelligenceProvider(claudePath)`.
+2. **TopicSummarizer** — Session-completion auto-summarization
+   instantiated its own Claude provider via dynamic import.
+3. **JobReflector** (via `instar reflect` CLI) — `resolveIntelligence`
+   helper built Claude unconditionally.
+
+Fix: each call site now first consults `sharedIntelligence` (built
+upstream by `buildIntelligenceProvider({ framework: resolvedFramework })`)
+and only falls back to constructing a Claude provider when
+`sharedIntelligence` is unavailable. The reflect CLI uses
+`frameworkFromEnv()` directly since it doesn't share state with the
+server boot path.
+
+Files touched:
+- `src/commands/server.ts` — 2 call sites:
+  - RelationshipManager init now reuses `sharedIntelligence` and emits
+    `LLM-supervised (Codex CLI)` (or Claude, or fallback) in the boot log.
+  - TopicSummarizer init prefers `sharedIntelligence` over a dynamic
+    Claude import.
+- `src/commands/reflect.ts` — `resolveIntelligence` now uses the
+  factory + `frameworkFromEnv` first; Claude-only path remains as a
+  documented last-ditch fallback.
+
+## Decision-point inventory
+
+- **Reuse sharedIntelligence vs build fresh** — `add` (reuse). The
+  framework already resolved once at boot via `resolvedFramework`.
+  Building a fresh provider per subsystem (a) duplicates the spawn
+  cost on first use, and (b) creates a footgun where one subsystem
+  gets Claude while another gets Codex on the same boot. Reuse keeps
+  every subsystem on the same plane.
+- **Preserve the Claude fallback** — `add`. When
+  `sharedIntelligence` couldn't be built (no Claude AND no Codex
+  installed), the call sites still try the legacy ClaudeCli
+  constructor as a last-ditch. Drops to heuristic-only beyond that.
+  Symmetric with the existing `sharedIntelligence` fallback in
+  server.ts at line 2055.
+- **Reflect CLI's own factory call** — `add`. The reflect CLI runs
+  outside the server boot path; it can't reach `sharedIntelligence`.
+  Doing a fresh `buildIntelligenceProvider({ framework })` call there
+  is the right shape — same pattern the `instar route` CLI uses.
+
+## Signal vs authority
+
+This change doesn't shift any signal/authority boundaries — each
+subsystem still has its own LLM-supervised authority for its domain
+(identity resolution, topic summarization, reflection). The change is
+purely about WHICH framework's CLI carries those decisions.
+
+## Over-block / under-block analysis
+
+**Over-block:** None. The Claude fallback ensures any installation
+that was working before still works.
+
+**Under-block:** A user with Codex-only could see slightly different
+relationship/summary outcomes than a Claude-only user — that's the
+whole point of provider portability. Same Phase 5a fitness research
+that mapped tasks→models applies; nothing about the call shape
+changes.
+
+## Level-of-abstraction fit
+
+- Call-site change only; no new abstraction.
+- `sharedIntelligence` is already the framework-aware singleton; we're
+  just plumbing it where it should have plumbed originally.
+
+## Interactions
+
+- **`RelationshipManager`** — receives `sharedIntelligence` instead
+  of a fresh ClaudeCli. Same interface.
+- **`TopicSummarizer`** — same.
+- **`JobReflector`** — same.
+- **No interface changes** anywhere.
+
+## External surfaces
+
+- Boot-log copy change:
+  - Before: `Relationships loaded: 0 tracked (LLM-supervised (Claude CLI subscription))`
+  - After: `Relationships loaded: 0 tracked (LLM-supervised (Codex CLI))`
+    or `(Claude CLI subscription)` per `intelligenceSource`.
+- No new endpoints / env vars / config keys.
+
+## Rollback cost
+
+Trivial.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- End-to-end boot verification:
+  - Before: `Relationships loaded: 0 tracked (LLM-supervised (Claude CLI subscription))` even with `INSTAR_FRAMEWORK=codex-cli`.
+  - After: `Relationships loaded: 0 tracked (LLM-supervised (Codex CLI))` with `INSTAR_FRAMEWORK=codex-cli`.
+- No new unit tests: the change is a call-site re-pointer to the
+  existing `sharedIntelligence` singleton, which is already tested
+  upstream in `tests/unit/intelligenceProviderFactory.test.ts` and
+  `tests/unit/config-framework-routing.test.ts`. Adding a fresh
+  per-subsystem test would just re-assert the same factory plumbing.

package/upgrades/side-effects/tier-4c-codex-skip-git-repo-check.md

@@ -0,0 +1,105 @@
+# Side-effects review — Tier 4.C Codex non-git directory fix (release blocker)
+
+**Version / slug:** `tier-4c-codex-skip-git-repo-check`
+**Date:** `2026-05-16`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (single-flag addition; surfaced and verified by end-to-end smoke test that previously failed silently)
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md`
+
+## Summary of the change
+
+End-to-end smoke testing of `instar route` with `INSTAR_FRAMEWORK=codex-cli` produced silent classification failures (`taskPattern: "unclassified"`, `source: "auto-defaulted-unclassified"`) every time the state directory wasn't a git checkout. Investigation traced it to Codex CLI's pre-flight check:
+
+```
+Not inside a trusted directory and --skip-git-repo-check was not specified.
+```
+
+Codex refuses to run with `--cd <dir>` when `<dir>` isn't inside a git repo. Every `.instar/` state directory in a non-git project, every `/tmp/` smoke test, every CI test fixture would hit this. The provider silently returned the error to the caller, who fell back to UNCLASSIFIED — masking the failure as "low-confidence routing" rather than "Codex is broken on this machine."
+
+Fix: add `--skip-git-repo-check` to the `codex exec` arg list in `CodexCliIntelligenceProvider`. These calls are short deterministic reviewer / sentinel / canary prompts that don't depend on the cwd content; the git-trust check Codex does is for interactive coding sessions, not headless evaluation.
+
+This is a release blocker for morning testing — without it, every Codex-based agent on every non-git directory was silently degraded.
+
+Files touched:
+- `src/core/CodexCliIntelligenceProvider.ts` — added `'--skip-git-repo-check'` to the args array, with a comment explaining why.
+- `tests/unit/CodexCliIntelligenceProvider.test.ts` — new, 5 tests; uses a tiny fake-codex shell script (echoes its argv) so the test asserts the exact spawn args without needing real codex installed.
+
+## Decision-point inventory
+
+- **Pass `--skip-git-repo-check` always vs conditionally** — `add`
+  (always). Reviewers/sentinels/canaries never depend on cwd-as-git.
+  Making the flag conditional ("only when the dir isn't a repo") adds
+  a stat() call and a branch for no benefit — Codex still does its own
+  check, and our calls genuinely don't care. Symmetry with how the
+  ClaudeCli provider doesn't gate on git status either.
+- **Surface the failure via tests vs runtime degradation** — `add`
+  (tests). The previous behavior — silent UNCLASSIFIED — masked the
+  failure. The new fake-codex-script test asserts the exact arg list
+  so a future regression (someone drops the flag accidentally) is
+  caught at commit time.
+
+## Signal vs authority
+
+This is a control-primitive correctness fix, not a signal/authority
+question. The provider's `evaluate()` is the authority for "did the
+LLM produce output?" — passing the flag is the correct invocation
+shape Codex requires for that authority to function in non-git dirs.
+
+## Over-block / under-block analysis
+
+**Over-block:** None. The flag is purely a permission grant; Codex's
+sandbox setting (`--sandbox read-only` by default) still restricts
+what the spawned process can do. The flag just disables a pre-flight
+refusal that doesn't apply to our usage pattern.
+
+**Under-block:** None. The flag's purpose is to permit running in
+non-git dirs. The sandbox mode is unchanged.
+
+## Level-of-abstraction fit
+
+- Stays inside `CodexCliIntelligenceProvider` — single-flag change in
+  the spawn arg list. No new abstraction needed.
+- Comment in the provider documents WHY the flag is on (specifically
+  references the failure mode it fixes), so a future reader doesn't
+  drop the flag thinking "this seems risky."
+
+## Interactions
+
+- **Every IntelligenceProvider consumer on Codex** (reviewer,
+  sentinel, canary, classifier, override detector, route CLI) —
+  now actually returns Codex output instead of silent errors.
+  Behavior change: positive. No interface change.
+- **`ClaudeCliIntelligenceProvider`** — not modified. Claude Code
+  doesn't have an equivalent git-trust gate.
+
+## External surfaces
+
+- No new endpoints.
+- No new environment variables.
+- No new config keys.
+- Behavior change on the wire: every `codex exec` invocation now
+  includes one additional flag. Visible only to anyone trace-
+  capturing the spawn args.
+
+## Rollback cost
+
+Trivial. `git revert` restores the prior arg list. State-shape and
+public interfaces are unchanged.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- New unit tests: `tests/unit/CodexCliIntelligenceProvider.test.ts` —
+  5 tests covering:
+  - `--skip-git-repo-check` is always present.
+  - Full arg ordering: `exec`, `--model`, `--sandbox`, `--cd`, `--skip-git-repo-check`, then positional prompt.
+  - Custom sandbox mode honored.
+  - Stdout trim contract.
+  - Non-zero exit produces a wrapped `Codex CLI error: …`.
+- End-to-end smoke verification (`INSTAR_FRAMEWORK=codex-cli node
+  dist/cli.js route "refactor python helper" --dir /tmp/codex-smoke-2 --json`):
+  - Before: `taskPattern: "unclassified"`, `source: "auto-defaulted-unclassified"`, 0.8s wall-clock (failed in 0ms internal time).
+  - After: `taskPattern: "code-refactor-python"`, `source: "auto-defaulted-no-topic"`, ~4-5s wall-clock (real Codex call).
+- This reproduces the bug-fix evidence bar: failure mode reproduced
+  in dev BEFORE the fix; same invocation produces the corrected
+  outcome AFTER.

package/upgrades/side-effects/tier0-leaking-codex-dev-path.md

@@ -0,0 +1,70 @@
+# Side-effects review — Tier 0 release blocker: leaking dev path in openai-codex config
+
+**Version / slug:** `tier0-leaking-codex-dev-path`
+**Date:** `2026-05-16`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (the bug is a literal string default; the fix is a delegation to existing detection infrastructure with a regression-test gate)
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md` (path-constraint-style discipline applied to Codex too)
+
+## Summary of the change
+
+A v1.0.0 audit caught a hardcoded developer-specific path baked into the Codex adapter default config:
+
+```ts
+codexPath: env['CODEX_PATH'] || '/Users/justin/.asdf/installs/nodejs/22.18.0/bin/codex',
+```
+
+This is a release blocker: any install that doesn't have asdf+nodejs-22.18.0+justin's username at that exact prefix would fail. Replaced with PATH-based detection delegating to a new framework-agnostic `detectFrameworkBinary(name)` helper in `src/core/Config.ts`.
+
+While fixing the immediate bug, also generalized the binary detection (Tier 1.A from the audit plan) — `detectFrameworkBinary` accepts any framework name (`claude`, `codex`, `gemini`, `aider`, `goose`, `cursor-cli`, `opencode`, `plandex`) and searches: framework-specific install locations, system paths, npm-global bin, nvm-managed bin, then PATH lookup. Adds a `detectCodexPath()` convenience wrapper sibling to existing `detectClaudePath()`. Both wrappers delegate to the generic function.
+
+Source-level regression test added: `tests/unit/detectFrameworkBinary.test.ts` scans config source files and fails if any literal `.asdf/installs/nodejs/<version>` path slug is hardcoded again.
+
+Files touched:
+- `src/core/Config.ts` — new `detectFrameworkBinary(name)` function; existing `detectClaudePath()` delegates to it; new `detectCodexPath()` sibling.
+- `src/providers/adapters/openai-codex/config.ts` — `configFromEnv()` defaults switched from hardcoded path to `detectCodexPath() || 'codex'`; tmuxPath also routed through `detectTmuxPath()`.
+- `tests/unit/detectFrameworkBinary.test.ts` — new, 6 cases including a source-level regression guard.
+
+## Decision-point inventory
+
+- **Binary path resolution** — `modify`. The decision point hasn't changed shape (input: framework name, output: path-or-null). The implementation now generalizes across frameworks rather than hardcoding per-framework.
+- **Config-default fallback** — `modify`. When `CODEX_PATH` env var is unset, the fallback path is now dynamically detected rather than baked in.
+- **Source-level regression test** — `add`. New deterministic guard ensures future PRs can't reintroduce the leak.
+
+## Signal vs authority
+
+Pure utility function. No authority surface.
+
+## Over-block / under-block analysis
+
+**Over-block:** None. The new `detectFrameworkBinary` covers every install location the prior `detectClaudePath` covered, plus framework-specific `~/.codex/bin/codex` etc. Strictly broader.
+
+**Under-block:** On machines that have the binary installed in an unusual location (not in the candidate list AND not in PATH), detection returns null and the adapter's `codexPath` becomes the literal string `'codex'` — the spawn call would then fail with ENOENT at execution time. This is correct behavior: the failure surfaces at adapter-call time with a clear error rather than at module-load time with a silent default. Documented in the config doc-comment.
+
+## Level-of-abstraction fit
+
+- `detectFrameworkBinary` lives in `src/core/Config.ts` alongside the other detection helpers. Single source of truth.
+- The adapter's `configFromEnv` is now a thin layer over the generic detection.
+- Adding a new framework needs (a) a case branch for framework-specific install paths if it has one, (b) addition to the `FrameworkBinary` union type. No new code paths.
+
+## Interactions
+
+- **Existing `detectClaudePath()` callsites** — unchanged behavior. Function is now a one-line wrapper but the contract is identical.
+- **`detectTmuxPath()`** — unchanged. Pre-existing tmux detection.
+- **Tests** — passed before; pass after. No regressions.
+
+## External surfaces
+
+- New exports: `detectFrameworkBinary`, `detectCodexPath`, `FrameworkBinary` type.
+- No new endpoint, no new CLI command, no new config field. The CODEX_PATH env var was already documented.
+
+## Rollback cost
+
+Trivial. `git revert` restores the hardcoded path — which would re-introduce the release blocker, so revert is itself an anti-action.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/detectFrameworkBinary.test.ts tests/unit/Config.test.ts tests/unit/ConfigDefaults.test.ts` — 27/27 pass.
+- Source-level regression guard added — covers all four config files (core Config + three provider adapter configs).
+- Tested locally that `detectCodexPath()` returns the correct path on this machine via PATH lookup.

package/upgrades/side-effects/tier1b-multi-provider-credentials.md

@@ -0,0 +1,79 @@
+# Side-effects review — Tier 1.B multi-provider credentials
+
+**Version / slug:** `tier1b-multi-provider-credentials`
+**Date:** `2026-05-16`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (additive shape with backwards-compat migration, complete branch coverage in unit tests)
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md` (the spine of multi-provider — was previously locked to a single `anthropicApiKey` field)
+
+## Summary of the change
+
+The audit identified `config.sessions.anthropicApiKey` as the spine of single-provider lock-in: every spawn path threaded that one field through, and there was no shape for "I have an OpenAI key for Codex AND an Anthropic OAuth token for Claude."
+
+This change adds the multi-provider credentials structure without breaking existing installs:
+
+1. **New types** in `src/core/types.ts`:
+   - `ProviderCredentialKind = 'oauth-token' | 'api-key'`
+   - `ProviderCredential = { kind, value, baseUrl? }`
+   - `SessionManagerConfig.credentials?: Record<string, ProviderCredential>` (keys = provider ids)
+   - `anthropicApiKey` / `anthropicBaseUrl` marked `@deprecated` but still readable for backwards-compat.
+
+2. **New helpers** in `src/core/Config.ts`:
+   - `buildCredentialsMap(sessionsConfig)`: migrates legacy fields into the new map at load time.
+   - `getProviderCredential(config, providerId)`: lookup that consults the map first and falls back to the legacy field for 'anthropic' so existing installs keep working.
+   - `buildProviderEnvFlags(providerId, credential)`: maps a credential to the right env vars for tmux spawn. Knows Anthropic (oauth-token vs api-key with mutual exclusion + base-URL), OpenAI/Codex (api-key only — Codex uses auth.json for OAuth), Google/Gemini. Unknown providers return empty (safe no-op).
+
+3. **Config loader** now populates `credentials` at load time via migration.
+
+Existing SessionManager spawn paths still reference `this.config.anthropicApiKey` directly — they will be migrated to use `getProviderCredential('anthropic')` and `buildProviderEnvFlags('anthropic', cred)` in a subsequent slice. The new helpers are in place; consumers swap over incrementally so no spawn-path behavior changes today.
+
+Files touched:
+- `src/core/types.ts` — new `ProviderCredentialKind`, `ProviderCredential` types; `SessionManagerConfig.credentials` field + deprecation notes on legacy fields.
+- `src/core/Config.ts` — `buildCredentialsMap`, `getProviderCredential`, `buildProviderEnvFlags`. Loader populates `credentials` from legacy fields.
+- `tests/unit/providerCredentials.test.ts` — new, 14 cases.
+
+## Decision-point inventory
+
+- **Credential lookup** — `add`. New surface: `getProviderCredential(config, providerId)`. Existing callers that read `config.anthropicApiKey` directly keep working — they read the legacy field. New code uses the helper.
+- **Env-var injection mapping** — `add`. New surface: `buildProviderEnvFlags(providerId, cred)`. Existing inline mapping in SessionManager (lines 684-686 and 1279-1281) keeps working — they'll be migrated in the next slice.
+- **Config schema** — `extend`. New optional `credentials` field. Legacy fields preserved with deprecation notice.
+
+## Signal vs authority
+
+These are utility functions and a data shape. No authority surface. SessionManager remains the spawn-time authority; this slice gives it cleaner data to consult.
+
+## Over-block / under-block analysis
+
+**Over-block:** None. The legacy fields still flow through as before. New code that hasn't migrated yet doesn't see any change.
+
+**Under-block:** Migration is incremental. Until SessionManager's spawn paths consume `getProviderCredential` + `buildProviderEnvFlags`, the single-provider lock-in is structurally unchanged for spawned subprocesses — the change is purely additive infrastructure. The credentials helper exists but isn't called from any production path yet. Documented in the JSDoc.
+
+## Level-of-abstraction fit
+
+- Provider ids are strings (e.g. `'anthropic'`, `'openai'`, `'google'`). Matches the existing `ProviderId` brand used in `src/providers/`. No new id system.
+- Credential kind (oauth-token vs api-key) is the minimum discriminator that drives different env-var behaviors. Adding more kinds (PAT, JWT) is additive — `ProviderCredentialKind` is a union, extend it.
+- Provider-specific env mapping lives in one switch statement in `buildProviderEnvFlags`. New providers: add a case branch.
+
+## Interactions
+
+- **`SessionManagerConfig` consumers** (SessionManager, Config loader, server.ts, tests) — unchanged signatures. New `credentials` field is optional.
+- **SessionManager spawn paths** at lines 684-686 and 1279-1281 — UNCHANGED in this slice. Migration to the new helper happens in a follow-up to avoid breaking behavior under load.
+- **`buildCredentialsMap` legacy migration** — fires at every config load. Idempotent (only fills in if not explicitly set).
+- **No existing source files MODIFIED except the additive ones** noted above.
+
+## External surfaces
+
+- New exports: `ProviderCredentialKind`, `ProviderCredential` (types); `getProviderCredential`, `buildProviderEnvFlags` (functions).
+- New optional `credentials` field on `SessionManagerConfig`.
+- The legacy `anthropicApiKey` / `anthropicBaseUrl` fields are still part of the public type but now JSDoc-marked `@deprecated` with v1.0.0 migration guidance.
+
+## Rollback cost
+
+Trivial. `git revert` removes one new test file + the additions to types.ts / Config.ts. No production callsites consume the new helpers yet; nothing breaks.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/providerCredentials.test.ts` — 14/14 pass.
+- Coverage: legacy migration (3 cases), credentials-map-wins-over-legacy, oauth-detection from `sk-ant-oat` prefix, baseUrl propagation, unknown-provider null, env-flag building for anthropic (oauth + api-key + baseUrl), openai api-key, openai oauth (no env emitted), google api-key, unknown-provider safe-no-op.
+- No real-API verification needed — pure type + utility surface.

package/upgrades/side-effects/tier1c-codex-intelligence-provider.md

@@ -0,0 +1,80 @@
+# Side-effects review — Tier 1.C CodexCliIntelligenceProvider + factory
+
+**Version / slug:** `tier1c-codex-intelligence-provider`
+**Date:** `2026-05-16`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (mirrors ClaudeCliIntelligenceProvider's shape exactly; factory is a simple switch with exhaustiveness check)
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md`
+
+## Summary of the change
+
+The audit named this as the single most load-bearing missing piece: until v0.x, `ClaudeCliIntelligenceProvider` was the ONLY `IntelligenceProvider` implementation, so every reviewer / sentinel / canary / JobReflector that depends on the abstraction ran `claude -p` exclusively. "Supports Codex" was a runtime promise we couldn't keep.
+
+This change adds the sibling implementation plus the factory that picks between them:
+
+1. **`CodexCliIntelligenceProvider`** in `src/core/CodexCliIntelligenceProvider.ts`:
+   - Same interface as ClaudeCliIntelligenceProvider (`evaluate(prompt, options) → Promise<string>`).
+   - Routes through `codex exec --model <tier> --sandbox <mode> --cd <wd> <prompt>`.
+   - Reuses Codex adapter's `resolveCliModelFlag` so `fast`/`balanced`/`capable` tiers map correctly (`gpt-5.2` / `gpt-5.3-codex` / `gpt-5.4`).
+   - Strips the same `CLAUDECODE` / `CLAUDE_SESSION_ID` env markers as the Claude provider (defense-in-depth — Codex itself doesn't care, but consistent hygiene means nested-session quirks can't leak across providers).
+   - Closes stdin explicitly to avoid the EOF-hang bug we already fixed once in the Codex adapter's transport layer.
+
+2. **`buildIntelligenceProvider(options)` factory** in `src/core/intelligenceProviderFactory.ts`:
+   - `framework: 'claude-code' | 'codex-cli'` (default `claude-code`).
+   - Optional `binaryPath` override; falls back to `detectClaudePath()` / `detectCodexPath()`.
+   - Returns null when the required binary can't be located. Caller decides what to do.
+   - Exhaustiveness check at the default branch — extending `IntelligenceFramework` without adding a switch case is a type error.
+
+3. **`frameworkFromEnv(env)`** helper:
+   - Parses `INSTAR_FRAMEWORK` env var. Accepts `claude-code` / `claude` / `CLAUDE`, `codex-cli` / `codex` / `CODEX`.
+   - Returns null for unset, empty, or unknown values — caller applies the default.
+
+Files touched:
+- `src/core/CodexCliIntelligenceProvider.ts` — new, 92 LOC.
+- `src/core/intelligenceProviderFactory.ts` — new, 88 LOC.
+- `tests/unit/intelligenceProviderFactory.test.ts` — new, 10 cases.
+
+## Decision-point inventory
+
+- **IntelligenceProvider selection** — `add`. The composition root (not yet wired) will call `buildIntelligenceProvider({ framework: configuredFramework })`. Today every reviewer/sentinel constructs an IntelligenceProvider directly via `new ClaudeCliIntelligenceProvider(path)`; that wiring migrates to the factory in the server-composition-root slice.
+- **Codex evaluate() shape** — `add`. New surface mirrors Claude's contract exactly. Errors reject (not collapse), so callers can fall back the same way they do for Claude.
+
+## Signal vs authority
+
+Both providers are signal producers (return text). They have no blocking authority. The reviewer/sentinel/canary above them is the authority that decides what to do with the response.
+
+## Over-block / under-block analysis
+
+**Over-block:** None. The factory adds a new path; the existing direct-construction path keeps working.
+
+**Under-block:** Until the composition root migrates to use the factory, the only IntelligenceProvider running in production is still ClaudeCli. Codex installs can't get LLM-backed reviewer/sentinel benefits yet. This is the next slice's job.
+
+## Level-of-abstraction fit
+
+- The two implementations are siblings in `src/core/`. Adding Gemini, DeepSeek, etc. follows the same pattern.
+- The factory takes a framework name and returns a provider. No provider-specific options leak to the caller.
+- Model-tier resolution is delegated to per-adapter helpers — same separation of concerns that already existed.
+
+## Interactions
+
+- **`ClaudeCliIntelligenceProvider`** — unchanged. Both providers can coexist; the factory picks one per agent.
+- **Codex adapter `models.ts:resolveCliModelFlag`** — consumed by the new provider. No changes to the adapter.
+- **`detectClaudePath` / `detectCodexPath`** (Tier 0 work) — consumed for binary detection fallback.
+- **No existing source files modified** except for the additive new ones.
+
+## External surfaces
+
+- New exports: `CodexCliIntelligenceProvider`, `CodexCliIntelligenceProviderOptions`, `buildIntelligenceProvider`, `BuildIntelligenceProviderOptions`, `IntelligenceFramework`, `frameworkFromEnv`.
+- New env var recognized: `INSTAR_FRAMEWORK` (claude-code / claude / codex-cli / codex, case-insensitive).
+- No new CLI command, no new config field shipped yet — the framework selection is env-driven for v1.0.0 and will get a config-file field in Phase 7 (migration design).
+
+## Rollback cost
+
+Trivial. `git revert` removes three new files. No production callsite consumes the factory yet.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/intelligenceProviderFactory.test.ts` — 10/10 pass.
+- Coverage: framework selection (claude-code, codex-cli, default), binary-path override propagation, workingDirectory propagation for Codex, INSTAR_FRAMEWORK parsing (all aliases + case insensitivity + unset + unknown).
+- No real-API verification yet — the live `codex exec` round-trip happens in the E2E test slice (Tier 4.C).

package/upgrades/side-effects/tier1d-identity-renderer.md

@@ -0,0 +1,75 @@
+# Side-effects review — Tier 1.D IdentityRenderer
+
+**Version / slug:** `tier1d-identity-renderer`
+**Date:** `2026-05-16`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (deterministic file rendering + read; full branch coverage with tmpdir tests)
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md`
+
+## Summary of the change
+
+Audit Gap A flagged CLAUDE.md as the hardcoded primary identity file and AGENT.md as a partial generalization. This change makes AGENT.md the canonical source of truth and renders framework-specific shadow files (CLAUDE.md for Claude Code, AGENTS.md for Codex, GEMINI.md for Gemini) from it.
+
+Key contracts:
+
+1. **`.instar/AGENT.md` is canonical.** The renderer reads it and writes framework-specific shadows.
+2. **`AGENT.md` at the project root is a backwards-compat fallback** for installs that keep identity at the root (legacy pattern).
+3. **Shadow files carry an auto-generation banner** that names the source and warns against hand-editing.
+4. **Legacy CLAUDE.md installs migrate cleanly** via `bootstrapAgentMdFromShadow(projectDir)` — reads the legacy file, strips any existing banner, writes `.instar/AGENT.md` as the new source.
+5. **`detectFrameworkFromShadowFiles(projectDir)` infers framework** from which shadow files exist — useful when an existing install is being upgraded and we need to know which framework was previously selected.
+
+`ProjectMapper.detectProjectName` priority flipped: AGENT.md first, CLAUDE.md/AGENTS.md fallback. Existing installs that have only CLAUDE.md continue to work; new installs read from AGENT.md.
+
+The renderer does NOT touch existing CLAUDE.md until a render is explicitly called — no migration runs automatically. The composition root in a later slice will call `renderIdentity` at boot and `bootstrapAgentMdFromShadow` when AGENT.md is missing.
+
+Files touched:
+- `src/core/IdentityRenderer.ts` — new, 167 LOC.
+- `src/core/ProjectMapper.ts` — name-detection priority flip + KEY_FILE_PATTERNS include AGENT.md/AGENTS.md/GEMINI.md alongside CLAUDE.md.
+- `tests/unit/IdentityRenderer.test.ts` — new, 16 cases.
+
+## Decision-point inventory
+
+- **Identity-file lookup priority** — `modify`. ProjectMapper now checks `.instar/AGENT.md` then root `AGENT.md` then CLAUDE.md then AGENTS.md. The fall-through preserves backwards-compat.
+- **Shadow rendering** — `add`. New deterministic pipeline (AGENT.md → CLAUDE.md/AGENTS.md/GEMINI.md). No render is automatic — caller explicitly invokes `renderIdentity`.
+- **Framework detection from layout** — `add`. New `detectFrameworkFromShadowFiles` infers framework from shadow file presence. Used by migration.
+- **Migration bootstrap** — `add`. `bootstrapAgentMdFromShadow` creates canonical AGENT.md from a legacy CLAUDE.md, banner-stripped.
+
+## Signal vs authority
+
+These are deterministic file operations. The renderer doesn't decide anything — caller decides when to render. ProjectMapper's name-detection is the same authority it was before; only the lookup order changed.
+
+## Over-block / under-block analysis
+
+**Over-block:** None. Existing installs with only CLAUDE.md keep working — ProjectMapper still finds it (just lower priority than AGENT.md). The renderer is opt-in; nothing is automatically overwritten.
+
+**Under-block:** Caller must remember to call `renderIdentity` after editing AGENT.md to keep shadows in sync. Documented in JSDoc. A future slice could add a file-watcher that auto-renders, but for v1.0.0 explicit invocation is simpler and safer (avoids spurious writes during indexing).
+
+## Level-of-abstraction fit
+
+- The renderer lives in `src/core/` alongside other core helpers. Pure file I/O — no provider abstractions baked in.
+- Framework→shadow-filename mapping is a single exported const (`FRAMEWORK_SHADOW_FILES`). Adding Gemini-CLI (`GEMINI.md`) was a 1-line addition for this slice. Future frameworks: same.
+- ProjectMapper change is minimally invasive — just reordered the lookup loop.
+
+## Interactions
+
+- **`init` and scaffold templates** — not yet updated; they still generate CLAUDE.md directly. Migration to render is part of Tier 6.A or the init-scaffold-update slice.
+- **`PostUpdateMigrator`** — still has ~8-10 hardcoded `CLAUDE.md` paths. Those will be migrated in Tier 2.G (Identity Layout Resolver consumers).
+- **`ProjectMapper.detectProjectName`** — now finds AGENT.md first. Tested via the renderer tests indirectly (they create AGENT.md in tmpdirs); explicit ProjectMapper tests aren't changed (no regression).
+- **No existing tests broken** — checked with `tsc --noEmit` clean + targeted vitest run.
+
+## External surfaces
+
+- New exports: `renderIdentity`, `RenderIdentityOptions`, `RenderIdentityResult`, `IdentityRendererError`, `FRAMEWORK_SHADOW_FILES`, `detectFrameworkFromShadowFiles`, `bootstrapAgentMdFromShadow`.
+- ProjectMapper's KEY_FILE_PATTERNS now lists AGENT.md/AGENTS.md/GEMINI.md alongside CLAUDE.md.
+- No new endpoint, no new CLI command, no new config field.
+
+## Rollback cost
+
+Trivial. `git revert` removes one new file + one new test + two small ProjectMapper edits. Existing shadow files (CLAUDE.md) keep working.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/IdentityRenderer.test.ts` — 16/16 pass.
+- Coverage: render all shadows, banner content, framework-name-in-banner, framework subset, root-AGENT.md fallback, .instar/AGENT.md preference when both exist, throw-on-missing-source, skip-unknown-framework, custom sourcePath, detect-from-shadow (3 cases), bootstrap-from-legacy-shadow (banner strip + .instar mkdir), null-on-no-shadow.
+- No real-API verification needed — pure file I/O.

package/upgrades/side-effects/tier2a-framework-aware-boot-prerequisite.md

@@ -0,0 +1,71 @@
+# Side-effects review — Tier 2.A framework-aware boot prerequisite
+
+**Version / slug:** `tier2a-framework-aware-boot-prerequisite`
+**Date:** `2026-05-16`
+**Author:** Echo (instar-developing agent)
+**Second-pass reviewer:** not required (pure-function helpers with exhaustiveness check + full branch coverage)
+**Driving spec:** `specs/provider-portability/04-anthropic-path-constraints.md`
+
+## Summary of the change
+
+Audit dimension #1 named this as a hard lock: `Config.load()` threw `Claude CLI not found` unconditionally when claude wasn't installed. Every non-Claude install rejected at startup. This change replaces the unconditional check with a framework-aware one — codex-cli installs only need the codex binary; claude-code installs only need claude.
+
+Implementation:
+
+1. **`resolveConfiguredFramework(configValue, envValue)`** — pure function that picks the active framework. Priority: explicit config field (`sessions.framework`) → `INSTAR_FRAMEWORK` env (with `codex`/`codex-cli`/`claude`/`claude-code` aliases) → default `claude-code` for backwards-compat.
+
+2. **`checkFrameworkPrerequisite({ configuredFramework, claudePathDetected, codexPathDetected })`** — pure function returning `{ satisfied: bool, error?: string }`. The error message is framework-specific and includes the install command.
+
+3. **`Config.loadConfig()` boot path** — refactored to call the two helpers above. Throws if the configured framework's binary is missing; previously threw if Claude was missing regardless of framework.
+
+For backwards-compat with existing spawn paths, the `SessionManagerConfig.claudePath` field now carries the configured framework's binary path. For claude-code installs that's the claude binary as always; for codex-cli installs it's the codex binary. SessionManager's spawn paths can keep reading `claudePath` unchanged; they'll be migrated to read a properly-named `frameworkBinaryPath` in a follow-up slice.
+
+Files touched:
+- `src/core/Config.ts` — new `resolveConfiguredFramework` and `checkFrameworkPrerequisite` exports; refactored `loadConfig` boot path to use them.
+- `tests/unit/frameworkPrerequisite.test.ts` — new, 11 cases.
+
+## Decision-point inventory
+
+- **Framework selection** — `add`. New `resolveConfiguredFramework` function. Used by Config.load; will be reused by other components that need to know which framework the user picked.
+- **Boot prerequisite check** — `modify`. Same authority (block startup when binary missing) but now framework-aware instead of always-Claude.
+- **Error message content** — `modify`. Per-framework guidance in the error string.
+
+## Signal vs authority
+
+Pure-function helpers. The authority (`throw new Error`) still lives in `Config.loadConfig`; the helpers just compute the decision. Decoupling makes the boot logic unit-testable without spinning up the full filesystem-aware load flow.
+
+## Over-block / under-block analysis
+
+**Over-block (rejecting installs that should work):** None. Existing claude-code installs continue to require Claude; existing installs that DON'T have INSTAR_FRAMEWORK set still default to claude-code. No new rejection mode.
+
+**Under-block (accepting installs that won't actually work):** A codex-cli install passes the boot check with only codex installed, but other code paths in SessionManager / reviewers / etc. still expect Claude. Those will surface ECC/claude-not-found errors at call-time. This is acceptable for v1.0.0 — boot succeeds, the failures are localized to the (small set of) Claude-specific code paths that the remaining tier-2 work will generalize.
+
+## Level-of-abstraction fit
+
+- Pure functions live alongside the existing detection helpers in `src/core/Config.ts`.
+- Exhaustiveness check at the default branch of `checkFrameworkPrerequisite` makes "add a new framework to the union without wiring it" a TypeScript error.
+- No new I/O paths, no new external dependencies.
+
+## Interactions
+
+- **`Config.loadConfig`** — calls the new helpers. Existing callers see the same throw behavior for claude-code installs; codex-cli installs now succeed where they previously failed.
+- **`SessionManagerConfig.claudePath`** — still populated as a string. For codex-cli installs it now contains the codex binary path. Existing SessionManager spawn paths keep working (they read `claudePath` and exec it; on codex-cli installs they'll be execing codex). Real spawning behavior for codex flows through the openai-codex adapter; reviewers and direct claude-CLI calls in v1.0.0 may misbehave on codex-cli installs until reviewer/sentinel slices migrate them. That's tier 2.B/C/etc. work.
+- **No existing tests broken** — checked.
+
+## External surfaces
+
+- New env var: `INSTAR_FRAMEWORK` (accepts claude-code/claude/codex-cli/codex, case-insensitive).
+- New config field: `sessions.framework: 'claude-code' | 'codex-cli'` (optional, defaults to claude-code).
+- New exports: `resolveConfiguredFramework`, `checkFrameworkPrerequisite`, `FrameworkPrerequisiteInput`, `FrameworkPrerequisiteResult`.
+
+## Rollback cost
+
+Trivial. `git revert` restores the unconditional Claude-required check.
+
+## Tests / verification
+
+- `npx tsc --noEmit` clean.
+- `vitest tests/unit/frameworkPrerequisite.test.ts` — 11/11 pass.
+- Coverage: resolveConfiguredFramework (config-wins, env-alias, defaults, whitespace handling) and checkFrameworkPrerequisite (every combination of {claude-code|codex-cli} × {claude installed | claude missing} × {codex installed | codex missing}) plus the v1.0.0 unlock assertion that codex-cli doesn't require Claude.
+- No real-API verification needed — pure logic.
+- Live verification of boot path happens in Tier 4.B (boot test with INSTAR_FRAMEWORK=codex and no Claude installed).