instar 1.2.10 → 1.2.12

package/upgrades/1.2.11.md

@@ -0,0 +1,65 @@
+# Upgrade Guide — v1.2.10 (Codex wizard model pin)
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**Fix: Codex setup wizard now passes a working model name.**
+
+`instar setup --framework codex-cli` and the v1.2.1 bareword runtime
+prompt both spawn Codex without passing `-m`/`--model`. Codex CLI
+falls back to its bundled default, `gpt-5.2-codex`, which OpenAI
+retired from ChatGPT-subscription accounts on 2026-04-14. The first
+real end-to-end install attempt by a ChatGPT-subscription user
+returned a 400 from OpenAI before the wizard could render:
+
+```
+The 'gpt-5.2-codex' model is not supported when using Codex with a
+ChatGPT account.
+```
+
+The fix:
+
+- New module constant `WIZARD_CODEX_MODEL = 'gpt-5.3-codex'` in
+  `src/commands/setup.ts`. The "balanced" tier from the existing
+  empirically-probed availability table at
+  `src/providers/adapters/openai-codex/models.ts`.
+- Both `codex exec` spawns in setup.ts (the setup-wizard launch and
+  the secret-setup micro-session) now include `-m
+  WIZARD_CODEX_MODEL` in the argv.
+- New unit-tier canary at
+  `tests/unit/setup-codex-model-canary.test.ts` AST-greps every
+  `framework === 'codex-cli'` exec block in setup.ts and refuses
+  any block that omits the flag. If a future PR adds a third codex
+  spawn without the flag, or removes the flag from either existing
+  one, CI fails.
+
+Spec: `specs/dev-infrastructure/codex-wizard-model.md`.
+ELI16: `specs/dev-infrastructure/codex-wizard-model.eli16.md`.
+Side-effects review: `upgrades/side-effects/fix-codex-wizard-model.md`.
+
+## What to Tell Your User
+
+The first-time-install path on Codex CLI now actually reaches the
+wizard. Before this release, typing the bareword instar command and
+picking Codex bounced off OpenAI with a model-not-supported error
+before anything visible happened. After this release, the same flow
+proceeds into the wizard prompt for identity, secrets, etc.
+
+If you already have an OPENAI API-key style auth and want to use a
+different Codex model, set the CODEX_MODEL env var — Codex CLI
+honors it and overrides the wizard default.
+
+## Summary of New Capabilities
+
+No new capabilities. Behavior fix on top of v1.2.9.
+
+## Evidence
+
+Reproduction prior: ran `npx instar@1.2.9` inside a cloned project,
+picked Codex CLI at the runtime prompt, observed the exact 400
+error above and the wizard never rendering.
+
+After: the canary unit test passes. End-to-end re-test on
+ChatGPT-subscription Codex auth pending on publish.

package/upgrades/1.2.12.md

@@ -0,0 +1,82 @@
+# Upgrade Guide — v1.2.12 (hybrid wizard for Codex runtime)
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**New: hybrid setup wizard for Codex-runtime installs.**
+
+`npx instar` → pick Codex CLI at the runtime prompt → now reaches
+an actual conversational walkthrough. Before this release, Codex
+ignored the wizard skill's behavioral contract and executed the
+entire setup non-interactively, leaving the user with a generic
+agent identity they never got to shape.
+
+The fix is a two-layer architecture under
+`src/commands/setup-wizard/`:
+
+1. **State machine** owns the conversation flow. Each state has a
+   structural prompt printed verbatim by instar, a deterministic
+   transition function, and (for action states) a side effect call
+   to existing CLI commands. Order is fixed in TypeScript code; no
+   LLM can drift it.
+
+2. **Codex driver** drives the state machine turn-by-turn. For each
+   conversational state, the driver runs `codex exec -s read-only
+   -m gpt-5.3-codex --ephemeral` with a tightly-constrained prompt
+   asking Codex to generate ONE warm 2-3 sentence intro paragraph.
+   The structural prompt is printed by instar; readline reads the
+   answer. Codex cannot use tools, cannot reword the question,
+   cannot decide to execute the setup itself.
+
+3. **Telegram setup phase** hands off to Codex as a full agentic
+   session (sandbox bypass + Playwright access) — driving the
+   browser is execution, which is Codex's strength.
+
+Claude-runtime users see no change. The Claude path keeps the
+existing `/setup-wizard` slash-command spawn.
+
+Settings the user picks during the wizard (agent name, focus,
+autonomy level, messaging channel) can all be changed later just
+by chatting the agent. The farewell text and the autonomy step's
+narrative both surface this affordance.
+
+Spec: `specs/dev-infrastructure/hybrid-wizard.md`.
+ELI16: `specs/dev-infrastructure/hybrid-wizard.eli16.md`.
+Side-effects review: `upgrades/side-effects/feat-hybrid-wizard.md`.
+
+## What to Tell Your User
+
+The setup wizard now walks you through identity, autonomy, and
+messaging conversationally, regardless of which runtime you picked.
+On Codex, the wizard runs as a state machine in instar itself with
+Codex generating the warm narrative for each step; on Claude it
+runs the same way it always has. Anything you set up can be
+changed later just by chatting your agent — no need to re-run setup.
+
+## Summary of New Capabilities
+
+- New module: `src/commands/setup-wizard/` (state machine + Codex
+  driver + model constants).
+- New CLI behavior: `npx instar` → pick Codex CLI → conversational
+  wizard with per-step narrative from Codex.
+- Existing CLI surface unchanged.
+
+## Evidence
+
+Reproduction prior to fix: ran v1.2.11 install via bareword `npx
+instar` → picked Codex. Codex received the wizard skill prompt and
+executed the entire setup non-interactively. Full log captured at
+`setup-logs.md` in the test project — 2940 lines, zero
+conversational walkthrough.
+
+After fix:
+- 12 new state-machine unit tests cover the choice resolver, graph
+  integrity, identity-answer threading, messaging branching, and
+  the post-server completion chain.
+- 5 updated canary tests cover the dispatch contract: setup.ts
+  imports `runCodexWizard` for codex-cli, no codex exec argv with
+  the wizard skill prompt remains in setup.ts, the driver's codex
+  exec spawns still pin `-m WIZARD_CODEX_MODEL`.
+- End-to-end re-test on the Codex install path pending on publish.

package/upgrades/side-effects/feat-hybrid-wizard.md

@@ -0,0 +1,122 @@
+# Side-effects review — Hybrid wizard
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER for Codex-runtime users. The bareword runtime prompt
+let users pick Codex, which then spawned Codex with the wizard skill.
+Codex ignored the skill's conversational contract and executed setup
+non-interactively. Generic agent identity, no walkthrough.
+
+After: precisely targeted. instar's state machine owns the
+conversation flow; Codex is restricted per-turn to narrative-only
+generation. Claude users see zero change (they keep the existing
+SKILL.md-driven spawn). API-key Codex users keep the same auth
+posture they had before. The agentic Telegram phase still uses
+Codex with full sandbox bypass — that's the right tool for browser
+automation.
+
+## 2. Level-of-abstraction fit
+
+A new directory `src/commands/setup-wizard/` holds three files:
+- `state-machine.ts` — pure data + transition functions, no I/O.
+- `codex-driver.ts` — I/O (codex spawn, readline, CLI subcommands).
+- `model-constants.ts` — single constant import target.
+
+setup.ts adds one dispatch branch (~12 LOC). It dynamically imports
+the codex driver only when the user picks Codex, keeping the
+setup.ts module load lightweight.
+
+The state machine is intentionally a flat record of states; no
+class hierarchy, no event emitters. Drivers consume it via simple
+lookups. Adding a state is one edit.
+
+## 3. Signal vs Authority compliance
+
+- The user's runtime choice from the bareword prompt remains an
+  operator-intent SIGNAL flowing into `enabledFrameworks` and the
+  wizard dispatch.
+- The state graph's transition functions are deterministic AUTHORITIES
+  for "what state comes next" given a user answer. Codex never sees
+  the transition function and cannot influence routing.
+- `WIZARD_CODEX_MODEL` is the AUTHORITY for which Codex model the
+  narrative spawns use, drawn from the existing empirically-probed
+  availability table at `src/providers/adapters/openai-codex/models.ts`.
+- The agentic Telegram phase respects the existing AUTHORITY for
+  Telegram bot creation (BotFather / OpenAI Codex's tool access /
+  Playwright MCP).
+
+## 4. Interactions with adjacent systems
+
+- **v1.2.1 runtime prompt** (`promptForFramework`): unchanged. Still
+  reads `1`/`2`/`codex` and returns the chosen runtime.
+- **`checkFrameworkPrerequisite`**: unchanged. Still validates the
+  chosen runtime's binary is detected.
+- **`ensureSecretBackend`** (Phase 2.5): unchanged in v1.2.12. Still
+  spawns the chosen framework with `/secret-setup` for the secret
+  backend choice. A future PR can route secret-setup through the
+  state machine too, but for v1.2.12 we keep that scope bounded.
+- **Existing wizard SKILL.md**: unchanged. Still owned by the Claude
+  path; the Codex path uses it ONLY as a reference target for the
+  Telegram-agentic phase prompt.
+- **CLI subcommands the wizard calls** (`init`, `user add`, `server
+  start`, `autostart install`): unchanged. The driver calls them via
+  `execFileSync('npx', ['instar', ...])` the same way the existing
+  SKILL.md tells Claude to call them.
+- **PR #299's canary**: updated. Previously asserted every `codex exec`
+  in setup.ts carries `-m WIZARD_CODEX_MODEL`. v1.2.12 asserts setup.ts
+  no longer has codex exec spawns (they moved into codex-driver.ts),
+  setup.ts dispatches via `runCodexWizard`, and the driver's codex
+  exec spawns still carry `-m WIZARD_CODEX_MODEL`.
+
+## 5. Rollback cost
+
+Low. Three new files in a new directory plus one ~12-LOC dispatch
+branch in setup.ts. The old `codex exec` argv shape in setup.ts is
+removed; reverting reintroduces it. Claude path untouched.
+
+`git revert` restores the v1.2.11 broken-on-Codex behavior. No state
+migration; no agent-installed-files changes; no `PostUpdateMigrator`
+work needed.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backwards-compatible.
+
+- Claude-runtime users: zero change.
+- Codex-runtime users: now get a working conversational wizard
+  driven by instar with Codex-generated narrative. Previously got
+  broken non-interactive setup.
+- API-key Codex users: auth posture unchanged. `CODEX_MODEL` env
+  still overrides the wizard's `-m` flag if they prefer a different
+  model.
+- No config schema change. No agent file template change. No hook
+  change.
+
+Drift surface: the state graph and per-turn narrative prompts. Both
+are flat data structures, so drift is visible in PR diffs. The
+canary covers the dispatch shape; manual review covers narrative
+prompt quality.
+
+## 7. Authorization / Trust posture
+
+No new authority. The per-turn narrative codex spawns use `-s
+read-only` (a strictly lower-privilege sandbox than the
+`--dangerously-bypass-approvals-and-sandbox` the existing wizard
+spawn uses). The Telegram-agentic phase keeps the existing sandbox-
+bypass posture so it can drive Playwright. The action states call
+`execFileSync('npx', ...)` for `init`, `user add`, `server start`,
+`autostart install` — the same CLI surface the existing wizard
+calls.
+
+No new auth, no new gate, no new privilege.
+
+## Outcome
+
+Ship. Closes the broken-on-Codex install experience that the v1.2.11
+instar-codey log surfaced. Per-framework specialization preserves
+each runtime's strengths (Claude's reliable skill-following, Codex's
+strong execution mode for agentic phases). Structure-as-guarantee
+prevents the regression class. Canary in CI guards the dispatch
+contract.

package/upgrades/side-effects/fix-codex-wizard-model.md

@@ -0,0 +1,102 @@
+# Side-effects review — Wizard codex spawn model pin
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER. The wizard launch and the secret-setup spawn both ran
+`codex exec` without `-m`, inheriting Codex CLI's bundled default
+(`gpt-5.2-codex`) which OpenAI retired from ChatGPT-subscription
+accounts on 2026-04-14. Every ChatGPT-subscription user hit a 400
+from OpenAI before the wizard could render. The previously-shipped
+runtime prompt (v1.2.1) made this reachable from the most natural
+install command, so the bug surfaced on Justin's first end-to-end
+test.
+
+After: precisely scoped. Two argv positions add `-m
+WIZARD_CODEX_MODEL`. No other code path touched. No over-block: API-
+key users who explicitly want a different model can still override
+via `CODEX_MODEL` env (Codex CLI honors it) or by editing their
+shell init — the constant only sets the wizard default.
+
+## 2. Level-of-abstraction fit
+
+One module-scope constant (`WIZARD_CODEX_MODEL`) in `setup.ts`
+captures the wizard's policy choice. Two existing argv builders
+consume it. No new abstraction layer.
+
+Importing from `src/providers/adapters/openai-codex/models.ts`'s
+TIER_TO_MODEL was considered and rejected — setup.ts has no other
+dependency on the openai-codex adapter, and the constant doesn't
+need to track every adapter-side update. If the available model
+set drifts, the canary will surface the regression via deployed
+errors faster than wiring a cross-module import would help.
+
+## 3. Signal vs Authority compliance
+
+The wizard's chosen model is a SIGNAL to Codex. Codex / OpenAI is
+the AUTHORITY for "is this model accessible to this auth posture."
+The change moves the SIGNAL into instar's explicit control instead
+of letting Codex's API-tier default decide for ChatGPT-subscription
+users.
+
+Memory `feedback_openai_path_constraints` (2026-05-16) is honored:
+no raw OPENAI_API_KEY routing, no API-tier model leakage to the
+subscription path.
+
+## 4. Interactions with adjacent systems
+
+- **`src/providers/adapters/openai-codex/models.ts`** — unchanged.
+  The adapter's TIER_TO_MODEL map remains the authoritative
+  empirically-probed availability table. The wizard's constant
+  mirrors one of its entries (`balanced` tier = `gpt-5.3-codex`).
+- **`src/core/SessionManager.ts`** — unchanged. Non-wizard codex
+  spawns elsewhere in the codebase already pass model selection
+  via existing options paths.
+- **Existing `instar setup --framework codex-cli`** path —
+  unchanged. The bareword prompt path (v1.2.1) and the explicit
+  subcommand path both flow through the same `runSetup` function,
+  so both pick up the fix in one place.
+- **Bareword runtime prompt** (v1.2.1) — unchanged. The prompt
+  routes intent (Claude vs Codex); the model flag is downstream of
+  the routing decision.
+- **`CODEX_MODEL` env var** — Codex CLI honors this env var to
+  override `-m`. API-key users who want the frontier model can
+  still set it (`CODEX_MODEL=gpt-5.2-codex npx instar`); the
+  default for subscription users is now safe.
+
+## 5. Rollback cost
+
+Trivial. One constant, two `-m WIZARD_CODEX_MODEL` insertions, one
+canary test. `git revert` restores the pre-fix broken-on-
+subscription behavior; nothing else depends on the constant.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backwards-compatible.
+
+- Existing CLI surface unchanged.
+- ChatGPT-subscription users: were broken, now work. No regression.
+- API-key users: same model selection behavior as before (Codex
+  CLI's `CODEX_MODEL` env overrides `-m`).
+- No agent-installed-files change → no `PostUpdateMigrator` work.
+
+Drift surface: if OpenAI retires `gpt-5.3-codex` from
+ChatGPT-subscription accounts in the future, the wizard will fail
+the same class of error. The canary test catches "the model flag
+is missing"; an additional follow-up canary should probe the
+configured model against the user's auth before launching the
+wizard, but that is out of scope here.
+
+## 7. Authorization / Trust posture
+
+No new authority. The fix selects a model already accessible to
+the existing auth posture; it does not add OPENAI_API_KEY support,
+does not bypass any gate, does not change sandbox or approval
+flags on the spawn.
+
+## Outcome
+
+Ship. Closes the broken-from-the-jump Codex install path on
+ChatGPT-subscription accounts. Canary test in CI prevents
+regression. Single-constant locality keeps the fix small.